---
title: "List contacts"
method: GET
path: "/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /contacts`

## Request

- Base URL: `https://api.supersendtx.com`
- URL: `https://api.supersendtx.com/contacts`
- Auth: HTTP bearer

## Query parameters

- `limit` integer
- `cursor` string
- `search` string
- `email` string, email
- `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained': Derived on read. A contact who is suppressed, or who has opted out of newsletter mail, always reads back as `unsubscribed` — there is one source of truth for consent and this reflects it.
- `list_id` string

## Response `200`

Contact list

- ListContactsResponse
  - `data` Contact[], required
    - `id` string, required
    - `email` string, email, required
    - `external_id` string, nullable, required: Your own id for this person, for joins back into your product
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `attributes` object, required: Flat, scalar-valued product state you sync up. Segments filter on it.
    - `status` 'subscribed' | 'unsubscribed' | 'bounced' | 'complained', required: Derived on read. A contact who is suppressed, or who has opted out of newsletter mail, always reads back as `unsubscribed` — there is one source of truth for consent and this reflects it.
    - `source` 'api' | 'import' | 'dashboard' | 'agent' | 'on_site', required: Where the contact was first created. `on_site` means an on-site message on your website captured the address.
    - `last_engaged_at` string, date-time, nullable, required: Last open or click across any campaign
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required

## Other responses

- `400`: Invalid cursor, invalid status filter, or blank `email` filter
- `401`: Missing or invalid API key

---

[API](https://skmtc.dev/ranla/apis/supersend-tx-api.md) · [All operations](https://skmtc.dev/ranla/apis/supersend-tx-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranla/apis/supersend-tx-api/revisions/e3e782652f50?raw)