List contacts
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 thenamefrom/v1/topics).subscription_status—OPT_INorOPT_OUT, scoping thetopicfilter to that status. Requirestopic; sent on its own it returns422 validation_failed.unsubscribe_all—true/falsemaster 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
Errors follow the RFC 7807 problem format — see the error reference.
data array<object> required Each entry in data:
email string<email> required unsubscribe_all boolean required Master opt-out — when true the contact receives no topic email.
attributes object required Custom attribute map as stored in SES. Always an object, never null.
topic_preferences array<object> required The contact's explicit per-topic choices. Topics the contact has
never set are absent — for those, the topic's
default_subscription_status applies, and SendOps enforces it at
send time. So an absent topic does not mean "will be mailed": on a
topic defaulting to OPT_OUT, a contact with no entry here has not
consented and will not be sent that topic's mail.
Each entry in topic_preferences:
topic_name string required The topic's name (see /v1/topics).
subscription_status string enum required One of: OPT_IN, OPT_OUT
created_at string<date-time> required updated_at string<date-time> required ses_sync object optional Present ONLY while the contact has not reached the customer's SES account yet; absent means synced. A 2xx on a contact write means SendOps has accepted and durably stored the change, not that SES has it — writes are mirrored afterwards, paced against the AWS account-wide budget of one contact request per second. Everything user-visible (segments, consent filtering, exports, sends) reads SendOps' own copy, so a pending mirror holds nothing back.
pagination object required Fields of pagination:
has_more boolean required next_cursor string | null optional code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json