Opt a contact out of a topic

POST /api/v1/contacts/{contactId}/topics/{topicId}/opt-out Stops one contact from receiving messages assigned to a topic. The contact stays subscribed to the list and can still receive messages for every other topic.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Path parameters

Parameter	Type	Description
`contactId`	string	Required. Identifier of the contact
`topicId`	string	Required. Identifier of the topic to stop sending

Example

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/contacts/$CONTACT_ID/topics/$TOPIC_ID/opt-out"

Response

200 OK — the topic preference is opted_out, including when it already was.
400 Bad Request — a path identifier is not a valid UUID; details identifies the field.
401 Unauthorized — missing or invalid key, or its owner left the organization.
403 Forbidden — the key's owner is a member, not an admin.
404 Not Found — the contact or topic is missing, belongs to another organization, or the two resources do not belong to the same organization.
429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`data.contactId`	string	Identifier of the contact
`data.topicId`	string	Identifier of the topic
`data.status`	string	Always `opted_out`

Example response

json

{
  "success": true,
  "data": {
    "contactId": "4d19c0a2-8f20-4fb8-9d55-39a88f86d778",
    "topicId": "a338c425-3115-4890-a01c-f2f6f012db93",
    "status": "opted_out"
  }
}

Notes

The call is idempotent. Repeating it does not create another preference or change the original opt-out date.
This call never changes the contact's global subscription status.