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

# List contacts

`GET /contacts`

Returns a paginated list of contacts (100 per page by default, up to 1000 via `per_page`).

Supports engagement filtering through `filter[...]` query parameters, so you can answer
questions like "who last opened over a year ago" without paging the whole account. All
filter conditions are AND-ed. Pass `count_only=true` to get just the number of matches —
the cheapest way to size an audience before acting on it.

## Query parameters

- `query` string
- `unsubscribed` boolean
- `email` string
- `per_page` integer
- `count_only` boolean
- `filter[status]` 'active' | 'engaged' | 'inactive' | 'new' | 'unconfirmed' | 'unsubscribed' | 'bounced' | 'invalid'
- `filter[last_opened_after]` string, date-time
- `filter[last_opened_before]` string, date-time
- `filter[last_clicked_after]` string, date-time
- `filter[last_clicked_before]` string, date-time
- `filter[last_sent_after]` string, date-time
- `filter[last_sent_before]` string, date-time
- `filter[created_after]` string, date-time
- `filter[created_before]` string, date-time
- `filter[never_opened]` boolean
- `filter[never_clicked]` boolean
- `filter[never_sent]` boolean
- `filter[in_list_ids]` integer[]
- `filter[not_in_list_ids]` integer[]
- `filter[tag_ids]` integer[]
- `filter[not_tag_ids]` integer[]

## Response `200`

Successful response

- union
  - object
    - `data` Contact[]
      - `id` integer
      - `email` string, email, required
      - `first_name` string
      - `last_name` string
      - `ip_address` string
      - `unsubscribed_at` string, date-time, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `current_page` integer
    - `total` integer
    - `per_page` integer
  - object — Returned when count_only is true
    - `count` integer
    - `filter` string — Human-readable rendering of the filter that was applied

## Other responses

- `401` — Unauthorized
- `422` — Invalid filter, or a list/tag id the account does not own

---

[API](https://skmtc.net/sendfox/apis/sendfox-api.md) · [All operations](https://skmtc.net/sendfox/apis/sendfox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sendfox/sendfox-api/revisions/c5728da3037f/schema)