> ## 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.

# List All Lists

> Retrieve all contact lists

Retrieve all contact lists for your domain.

## Examples

<CodeGroup>
  ```typescript JavaScript theme={null}
  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 });
  ```

  ```python Python theme={null}
  from mailbreeze import MailBreeze

  client = MailBreeze(api_key="sk_live_xxx")

  # List all contact lists
  result = await client.lists.list()
  print(f"Found {result.pagination.total} lists")

  for list in result.data:
      print(f"{list.name}: {list.contact_count} contacts")

  # With pagination
  result = await client.lists.list(page=2, limit=10)
  ```

  ```go Go theme={null}
  client := mailbreeze.NewClient("sk_live_xxx")

  // List all contact lists
  result, err := client.Lists.List(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  fmt.Printf("Found %d lists\n", result.Pagination.Total)

  for _, list := range result.Data {
      fmt.Printf("%s: %d contacts\n", list.Name, list.ContactCount)
  }

  // With pagination
  result, err := client.Lists.List(ctx, &mailbreeze.ListListsParams{
      Page:  2,
      Limit: 10,
  })
  ```

  ```php PHP theme={null}
  $mailbreeze = new MailBreeze('sk_live_xxx');

  // List all contact lists
  $response = $mailbreeze->lists->list();

  foreach ($response['data'] as $list) {
      echo $list['name'] . ": " . $list['totalContacts'] . " contacts\n";
  }
  ```

  ```rust Rust theme={null}
  let client = Client::new("sk_live_xxx");

  // List all contact lists
  let result = client.lists().list(None).await?;
  println!("Found {} lists", result.pagination.total);

  for list in result.data {
      println!("{}: {} contacts", list.name, list.contact_count);
  }

  // With pagination
  let result = client.lists().list(Some(ListListsParams {
      page: Some(2),
      limit: Some(10),
  })).await?;
  ```

  ```bash cURL theme={null}
  curl "https://api.mailbreeze.com/api/v1/contact-lists" \
    -H "Authorization: Bearer sk_live_xxx"
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique list ID.
</ResponseField>

<ResponseField name="name" type="string">
  List name.
</ResponseField>

<ResponseField name="description" type="string">
  List description.
</ResponseField>

<ResponseField name="totalContacts" type="integer">
  Total number of contacts in the list.
</ResponseField>

<ResponseField name="activeContacts" type="integer">
  Number of active contacts.
</ResponseField>

<ResponseField name="suppressedContacts" type="integer">
  Number of suppressed contacts.
</ResponseField>

<ResponseField name="tags" type="array">
  List tags.
</ResponseField>

<ResponseField name="customFields" type="object">
  Custom field definitions (if any).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when last updated.
</ResponseField>

```json Example Response theme={null}
{
  "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"
  }
}
```