---
title: "API reference: Suppressions"
url: "https://coldmeetings.com/docs/api/suppressions.md"
canonical_url: "https://coldmeetings.com/docs/api/suppressions"
last_updated: "2026-10-23"
type: "reference"
summary: "Read and extend the do not contact list of the ColdMeetings API. Bounces, complaints and opt outs are added to it automatically."
related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"]
---

# API reference: Suppressions

> **For AI agents:** the complete index of ColdMeetings pages is [llms.txt](https://coldmeetings.com/llms.txt). Every page is also served as markdown at its URL plus .md.

Read and extend the do not contact list of the ColdMeetings API. Bounces, complaints and opt outs are added to it automatically.

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](https://coldmeetings.com/docs/errors.md).

| Operation | What it does |
| --- | --- |
| [`GET /v1/suppressions`](#get-v1suppressions) | The do-not-contact list. |
| [`POST /v1/suppressions`](#post-v1suppressions) | Add 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](https://coldmeetings.com/docs/authentication.md).

### Query parameters

| Name | Type | Notes |
| --- | --- | --- |
| `limit` | integer | Rows per page, 1 to 100. More than 100 is held to 100. |
| `cursor` | string | The 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`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
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](https://coldmeetings.com/docs/authentication.md).

### Request body

Send a JSON object.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string | Yes | An email address. It is trimmed and lowercased. |
| `reason` | string | No | Default `"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`](https://coldmeetings.com/docs/errors.md#unauthorized), HTTP 401: The API key is missing, malformed, revoked or unknown.
- [`invalid_input`](https://coldmeetings.com/docs/errors.md#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`](https://coldmeetings.com/docs/errors.md#payload_too_large), HTTP 413: The body is over 256 KiB.
- [`rate_limited`](https://coldmeetings.com/docs/errors.md#rate_limited), HTTP 429: Too many requests for this key. Wait the number of seconds in `Retry-After`.

### Example request

```bash
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"}'
```

## Related

- [API reference](https://coldmeetings.com/docs/api.md)
- [Errors](https://coldmeetings.com/docs/errors.md)