Talk to us

Events

Open as markdown

For AI agents: the docs index is at /llms.txt, and every page is also served as markdown at its URL plus .md.

Delivery events. Bounces and complaints suppress the address at once, and enough complaints pause the campaign.

Base URL: YOUR_API_BASE_URL. Every request and response is JSON. Errors use one envelope.

OperationWhat it does
POST /v1/eventsRecord a sent, bounce or complaint event from the sending engine. Complaints suppress and can pause.

POST/v1/events#

Record a sent, bounce or complaint event from the sending engine. Complaints suppress and can pause.

Record what the sending engine reports. A bounce or a complaint adds the address to the do-not-contact list at once.

Authentication: send your API key as a bearer token. See Authentication.

Request body#

Send a JSON object.

FieldTypeRequiredNotes
campaign_idstringYesId of a campaign, such as cmp_2LmQx7RtVw3ZbN1pEs9fKd.
emailstringYesAn email address. It is trimmed and lowercased.
kindstringYesOne of sent, bounce, complaint.

Example body:

JSON
{
  "campaign_id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd",
  "email": "sam@contoso.example",
  "kind": "complaint"
}

Response#

Status 201 Created.

JSON
{
  "recorded": true,
  "campaign_paused": false
}
  • campaign_paused is true when a complaint made an active campaign cross the spam limit: 3 or more complaints, or more than 0.3 percent of sends once 100 have gone out.

Errors#

  • unauthorized, HTTP 401: The API key is missing, malformed, revoked or unknown.
  • invalid_input, HTTP 400: A body that is empty, is not JSON or fails validation also answers this, and the message names the field.
  • payload_too_large, HTTP 413: The body is over 256 KiB.
  • unknown_product, HTTP 404: No such campaign on this account.
  • rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

Shell
curl -X POST YOUR_API_BASE_URL/v1/events \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd",
  "email": "sam@contoso.example",
  "kind": "complaint"
}'
Documentation menu