contacts

List contacts

GET /v1/contacts

Auth required api.contacts.view

Returns the calling org's contacts, newest-first, with optional filters. Contacts mirror the recipients in your Amazon SES contact list; SendOps keeps them in sync but never sends on your behalf — sending stays on SendEmail with ListManagementOptions.

Recipient emails are returned in full: api.contacts.view is itself the PII gate, and the contact list is operator-managed by definition.

Filters compose with AND:

topic — only contacts with an explicit preference row for the named topic (use the name from /v1/topics).
subscription_status — OPT_IN or OPT_OUT, scoping the topic filter to that status. Requires topic; sent on its own it returns 422 validation_failed.
unsubscribe_all — true/false master opt-out flag.
attribute_key + attribute_value — JSONB containment match on a custom attribute (string equality on the value). Both must be sent together.

Cursors are opaque base64; stale or malformed cursors silently fall back to page 1. When no contact list is synced yet, an empty page is returned (use /v1/contact-list to detect that state explicitly).

Query parameters

limit integer optional

Page size (1–200). Default 50.

cursor string optional

Opaque cursor returned from the previous page.

topic string optional

Filter to contacts with a preference for this topic (topic name).

subscription_status string enum optional

Scope the topic filter to this status. Requires topic.

unsubscribe_all boolean optional

Filter by the contact's master opt-out flag.

attribute_key string optional

Custom attribute key to match. Must be sent with attribute_value.

attribute_value string optional

Custom attribute value to match (string equality). Must be sent with attribute_key.

Responses

200 Cursor-paginated list of contacts, newest-first application/json

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json

{ "data": [ { "email": "user@example.com", "unsubscribe_all": true, "attributes": {}, "topic_preferences": [ { "topic_name": "string", "subscription_status": "OPT_IN" } ], "created_at": "2026-05-17T20:00:00Z", "updated_at": "2026-05-17T20:00:00Z" } ], "pagination": { "has_more": true, "next_cursor": "string" } }