contacts
Create a contact
POST /v1/contacts
Auth required
api.contacts.manage
Creates a new contact in the org's SES contact list.
Returns 409 conflict when an active contact with that email already
exists. An archived contact (previously deleted via this API) is
reactivated instead and the call returns 201.
Attribute values are validated against the org's registry — an unknown
attribute key or a type mismatch returns 422 attribute_validation_failed
with a per-attribute errors[] array.
Supports the Idempotency-Key header: a duplicate key within 24 h
replays the original response.
Request body
Content type: application/json
{
"email": "user@example.com",
"attributes": {},
"unsubscribe_all": true,
"topic_preferences": [
{
"topic_name": "string",
"subscription_status": "OPT_IN"
}
],
"lists": {
"add": [
"00000000-0000-0000-0000-000000000000"
],
"remove": [
"00000000-0000-0000-0000-000000000000"
],
"set": [
"00000000-0000-0000-0000-000000000000"
]
}
}Responses
201 Contact created (or archived contact reactivated) 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
404 Resource not found application/problem+json
409 The mutation is rejected by a state rule rather than a bad request — e.g.
editing a git-backed (read-only) definition. The
code is conflict.
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