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

> Retrieve paginated list of contacts

List all contacts in a list with optional filtering by status.

## Path Parameters

<ParamField path="listId" type="string" required>
  The unique list ID (e.g., `lst_abc123`).
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of items per page (max 100).
</ParamField>

<ParamField query="status" type="string">
  Filter by contact status: `active`, `unsubscribed`, `bounced`, `complained`, or `suppressed`.
</ParamField>

## Examples

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { MailBreeze } from "mailbreeze";

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

  // List all contacts
  const { data, pagination } = await contacts.list();
  console.log(`Found ${pagination.total} contacts`);

  // List with status filter
  const { data } = await contacts.list({
    status: "active",
    page: 1,
    limit: 50,
  });

  for (const contact of data) {
    console.log(`${contact.email}: ${contact.firstName} ${contact.lastName}`);
  }
  ```

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

  client = MailBreeze(api_key="sk_live_xxx")
  contacts = client.contacts("lst_abc123")

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

  # List with status filter
  result = await contacts.list(
      status="active",
      page=1,
      limit=50,
  )

  for contact in result.data:
      print(f"{contact.email}: {contact.first_name} {contact.last_name}")
  ```

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

  // List all contacts
  result, err := contacts.List(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }
  fmt.Printf("Found %d contacts\n", result.Pagination.Total)

  // List with status filter
  result, err := contacts.List(ctx, &mailbreeze.ListContactsParams{
      Status: "active",
      Page:   1,
      Limit:  50,
  })

  for _, contact := range result.Data {
      fmt.Printf("%s: %s %s\n", contact.Email, contact.FirstName, contact.LastName)
  }
  ```

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

  // List all contacts
  $response = $mailbreeze->contacts->list('lst_abc123');
  $result = $response['data'];
  echo "Found " . $result['pagination']['total'] . " contacts\n";

  // List with status filter
  $response = $mailbreeze->contacts->list('lst_abc123', [
      'status' => 'active',
      'page' => 1,
      'limit' => 50,
  ]);
  $result = $response['data'];

  foreach ($result['contacts'] as $contact) {
      echo $contact['email'] . ": " . $contact['firstName'] . " " . $contact['lastName'] . "\n";
  }
  ```

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

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

  // List with status filter
  let result = contacts.list(Some(ListContactsParams {
      status: Some("active".to_string()),
      page: Some(1),
      limit: Some(50),
  })).await?;

  for contact in result.data {
      println!("{}: {} {}", contact.email, contact.first_name.unwrap_or_default(), contact.last_name.unwrap_or_default());
  }
  ```

  ```bash cURL theme={null}
  # List all contacts
  curl "https://api.mailbreeze.com/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts" \
    -H "Authorization: Bearer sk_live_xxx"

  # List with status filter
  curl "https://api.mailbreeze.com/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts?status=active&page=1&limit=50" \
    -H "Authorization: Bearer sk_live_xxx"
  ```
</CodeGroup>

## Response

<ResponseField name="data" type="array">
  Array of contact objects.

  <Expandable title="Contact object">
    <ResponseField name="id" type="string">
      Unique contact ID.
    </ResponseField>

    <ResponseField name="email" type="string">
      Contact's email address.
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Contact's first name.
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Contact's last name.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Contact's phone number.
    </ResponseField>

    <ResponseField name="customFields" type="object">
      Custom field values.
    </ResponseField>

    <ResponseField name="status" type="string">
      Contact status: `active`, `unsubscribed`, `bounced`, `complained`, or `suppressed`.
    </ResponseField>

    <ResponseField name="source" type="string">
      Acquisition source.
    </ResponseField>

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

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

    <ResponseField name="consentType" type="string">
      Type of consent: `explicit`, `implicit`, or `legitimate_interest`.
    </ResponseField>

    <ResponseField name="consentSource" type="string">
      Where consent was collected.
    </ResponseField>

    <ResponseField name="consentTimestamp" type="string">
      ISO 8601 timestamp when consent was given.
    </ResponseField>

    <ResponseField name="consentIpAddress" type="string">
      IP address from which consent was given.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="Pagination object">
    <ResponseField name="page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Items per page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of contacts.
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

```json Example Response theme={null}
{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "8f1701be-0d2a-4519-999c-0574a3d68668",
        "domainId": "6911cf4253eb3ff3b4de6215",
        "contactListId": "694fc1669e63563857ae8d72",
        "email": "user@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "customFields": {},
        "status": "active",
        "source": "console",
        "subscriptionToken": "b839501cb01ca878a01bd2d8d947ad3350b53afbf5370d3b3e1999c958ce309a",
        "createdAt": "2025-12-27T12:36:25.458Z",
        "updatedAt": "2025-12-27T12:36:26.851Z"
      }
    ],
    "contactListCustomFields": {},
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100141,
      "totalPages": 5008
    }
  },
  "meta": {
    "timestamp": "2025-12-27T13:40:36.952Z",
    "requestId": "94718148-9068-497e-86d8-69b42030d011",
    "path": "/api/v1/contact-lists/694fc1669e63563857ae8d72/contacts"
  }
}
```