List Email Contacts API

List email contacts for the organization attached to an API key.

List subscribers for the organization attached to the API key. The organization is resolved from the key, so no organization id or slug is accepted in the request.

Request

GET /api/v1/email/contacts

Authentication accepts either header:

x-api-key: org_api_key
Authorization: Bearer org_api_key

Query parameters:

Parameter	Type	Description
`limit`	`number`	Page size, capped at `100`. Defaults to `50`.
`cursor`	`string`	Cursor returned by a previous response.
`status`	`string`	`all`, `subscribed`, `unsubscribed`, `bounced`, or `complained`.
`tag`	`string`	Return contacts with this tag.
`search`	`string`	Bounded recent-contact search by email, first name, or last name.

curl -H "x-api-key: org_api_key" \
  "https://growth.example.com/api/v1/email/contacts?status=subscribed&limit=50"

Response

{
  "contacts": [
    {
      "id": "m57...",
      "email": "[email protected]",
      "firstName": "Lead",
      "lastName": null,
      "status": "subscribed",
      "source": "api",
      "customFields": {},
      "tags": ["newsletter"],
      "createdAt": 1783528574709,
      "updatedAt": 1783528574709
    }
  ],
  "cursor": "cursor-or-null",
  "isDone": false,
  "searchLimited": false
}

Error responses:

Status	Meaning
`400`	Invalid query parameter.
`401`	Missing or invalid API key.

Notes

The cursor is null when there are no more results.
Search mode scans a bounded recent-contact window and returns searchLimited: true when more rows may exist outside the search window.
Use GET /api/v1/me to confirm which organization the key targets.

Trigger Workflow Trigger Event