Talk to us

Suppressions

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.

The do not contact list. Bounces, complaints and opt out replies land here by themselves. You can add an address too.

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

OperationWhat it does
GET /v1/suppressionsThe do-not-contact list.
POST /v1/suppressionsAdd an address to the do-not-contact list.

GET/v1/suppressions#

The do-not-contact list.

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

Query parameters#

NameTypeNotes
limitintegerRows per page, 1 to 100. More than 100 is held to 100.
cursorstringThe next_cursor of the previous page, sent back unchanged to the same route. Leave it out for the first page. A cursor that was edited or came from another route is refused.

Response#

Status 200 OK.

JSON
{
  "suppressions": [
    {
      "email": "jordan@northwind.example",
      "reason": "spam complaint",
      "created_at": "2026-10-17T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}
  • reason is hard bounce, spam complaint, opted out by reply, or the reason you gave.
  • Oldest first, 20 a page. Send limit (1 to 100) for more, and send next_cursor back as cursor for the next page; next_cursor is null on the last page.

Errors#

  • unauthorized, HTTP 401: The API key is missing, malformed, revoked or unknown.
  • rate_limited, HTTP 429: Too many requests for this key. Wait the number of seconds in Retry-After.

Example request#

Shell
curl YOUR_API_BASE_URL/v1/suppressions \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY"

POST/v1/suppressions#

Add an address to the do-not-contact list.

Suppressed addresses are skipped by every later import and cannot be booked.

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

Request body#

Send a JSON object.

FieldTypeRequiredNotes
emailstringYesAn email address. It is trimmed and lowercased.
reasonstringNoDefault "added by customer". Up to 200 characters.

Example body:

JSON
{
  "email": "taylor@contoso.example",
  "reason": "asked by phone"
}

Response#

Status 201 Created.

JSON
{
  "email": "taylor@contoso.example",
  "added": true
}
  • added is false when the address was already on the list.

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.
  • 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/suppressions \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"taylor@contoso.example","reason":"asked by phone"}'
Documentation menu