Skip to main content
GET
/
api
/
v1
/
contact-lists
List All Lists
curl --request GET \
  --url https://api.example.com/api/v1/contact-lists
{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "totalContacts": 123,
  "activeContacts": 123,
  "suppressedContacts": 123,
  "tags": [
    {}
  ],
  "customFields": {},
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve all contact lists for your domain.

​
Examples

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

// List all contact lists
const { data, pagination } = await mailbreeze.lists.list();

console.log(`Found ${pagination.total} lists`);

for (const list of data) {
  console.log(`${list.name}: ${list.contactCount} contacts`);
}

// With pagination
const { data } = await mailbreeze.lists.list({ page: 2, limit: 10 });

​
Response

​
id
string
Unique list ID.
​
name
string
List name.
​
description
string
List description.
​
totalContacts
integer
Total number of contacts in the list.
​
activeContacts
integer
Number of active contacts.
​
suppressedContacts
integer
Number of suppressed contacts.
​
tags
array
List tags.
​
customFields
object
Custom field definitions (if any).
​
createdAt
string
ISO 8601 timestamp when created.
​
updatedAt
string
ISO 8601 timestamp when last updated.
Example Response
{
  "success": true,
  "data": [
    {
      "domainId": "6911cf4253eb3ff3b4de6215",
      "userId": "68da571fdc22fcf0773dcb33",
      "name": "Newsletter Subscribers",
      "description": "Weekly newsletter recipients",
      "totalContacts": 1523,
      "activeContacts": 1520,
      "suppressedContacts": 3,
      "tags": [],
      "createdAt": "2025-12-27T11:22:14.221Z",
      "updatedAt": "2025-12-27T13:40:37.798Z",
      "id": "694fc1669e63563857ae8d72"
    },
    {
      "domainId": "6911cf4253eb3ff3b4de6215",
      "userId": "68da571fdc22fcf0773dcb33",
      "name": "VIP Customers",
      "description": "High-value customers",
      "totalContacts": 245,
      "activeContacts": 245,
      "suppressedContacts": 0,
      "tags": ["vip", "premium"],
      "customFields": {
        "plan": { "type": "string" }
      },
      "createdAt": "2025-12-18T22:43:14.417Z",
      "updatedAt": "2025-12-26T13:37:42.519Z",
      "id": "69448382e35846d6098bcaff"
    }
  ],
  "meta": {
    "timestamp": "2025-12-27T13:47:55.962Z",
    "requestId": "27acddb1-c628-491c-abc7-cfb2d0b706ea",
    "path": "/api/v1/contact-lists"
  }
}