Get a list of contacts

Returns a paginated list of the account's contacts.

Pagination is cursor based. Every response carries a pagination object; pass its next_token value back as the token query parameter to fetch the next page, and stop when next_token is null. Cursors cannot be walked backwards, so prev_token and prev_url are always null. No total count is returned.

Filter values are validated rather than ignored. An unknown status, a non-integer list_id, a repeated filter parameter, or a malformed token is rejected with 422, so a mistyped filter can never widen the result set.

get

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Query parameters

list_idinteger · int64 · min: 1Optional

Return only contacts that belong to this contact list.

Example: 3229

statusstring · enumOptional

Return only contacts with this subscription status. Matches the status field of the returned contact.

Example: subscribedPossible values:

emailstringOptional

Return only contacts whose email contains this value (case-insensitive substring match). * and ? are matched literally, not as wildcards.

Example: john@

per_pageinteger · min: 1 · max: 50Optional

Number of contacts per page. Defaults to 25, maximum 50. Larger values are clamped to the maximum.

Default: 25Example: 25

tokenstringOptional

Opaque cursor taken from the next_token of a previous response. Omit it to fetch the first page. Tokens are not page numbers and must not be constructed by hand.

Example: WzE3NDI4MjA2MDAyMzAsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLWU1YzNmMmQ4YTEzMiJd

Responses

200

A paginated list of contacts.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

A filter value or the pagination cursor was invalid. The request is rejected instead of the filter being ignored.

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

get/api/contacts

cURL

curl -X GET https://mailtrap.io/api/contacts \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Filter by list, status and email substring
curl -X GET 'https://mailtrap.io/api/contacts?list_id=3229&status=subscribed&email=john%40' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Fetch the next page using the cursor from the previous response
curl -X GET 'https://mailtrap.io/api/contacts?per_page=25&token=WzE3NDI4MjA2MDAyMzAsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLWU1YzNmMmQ4YTEzMiJd' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
      "email": "[e-mail]",
      "created_at": 1742820600230,
      "updated_at": 1742820600230,
      "list_ids": [
        1,
        2
      ],
      "status": "subscribed",
      "fields": {
        "first_name": "John",
        "last_name": "Smith"
      }
    },
    {
      "id": "018dd5e3-f6d2-7c00-8f9b-000000000002",
      "email": "[e-mail]",
      "created_at": 1742906999123,
      "updated_at": 1742906999123,
      "list_ids": [
        3
      ],
      "status": "unsubscribed",
      "fields": {}
    }
  ],
  "pagination": {
    "token": null,
    "prev_token": null,
    "next_token": "WzE3NDI5MDY5OTkxMjMsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLTAwMDAwMDAwMDAwMiJd",
    "first_url": "https://mailtrap.io/api/contacts?per_page=25",
    "prev_url": null,
    "current_url": "https://mailtrap.io/api/contacts?per_page=25",
    "next_url": "https://mailtrap.io/api/contacts?per_page=25&token=WzE3NDI5MDY5OTkxMjMsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLTAwMDAwMDAwMDAwMiJd"
  }
}