---
title: "API reference: Events"
url: "https://coldmeetings.com/docs/api/events.md"
canonical_url: "https://coldmeetings.com/docs/api/events"
last_updated: "2026-10-23"
type: "reference"
summary: "Report sent, bounce and complaint events from the sending engine so the ColdMeetings API can suppress addresses and pause a campaign."
related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"]
---

# API reference: Events

> **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.

Report sent, bounce and complaint events from the sending engine so the ColdMeetings API can suppress addresses and pause a campaign.

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

| Operation | What it does |
| --- | --- |
| [`POST /v1/events`](#post-v1events) | Record 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](https://coldmeetings.com/docs/authentication.md).

### Request body

Send a JSON object.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `campaign_id` | string | Yes | Id of a campaign, such as `cmp_2LmQx7RtVw3ZbN1pEs9fKd`. |
| `email` | string | Yes | An email address. It is trimmed and lowercased. |
| `kind` | string | Yes | One 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`](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.
- [`unknown_product`](https://coldmeetings.com/docs/errors.md#unknown_product), HTTP 404: No such campaign on this account.
- [`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/events \
  -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd",
  "email": "sam@contoso.example",
  "kind": "complaint"
}'
```

## Related

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