--- title: "API reference" url: "https://coldmeetings.com/docs/api.md" canonical_url: "https://coldmeetings.com/docs/api" last_updated: "2026-10-23" type: "reference" summary: "Every ColdMeetings API operation in seven resource groups, generated from the API OpenAPI document, with request fields, responses and errors." related: ["https://coldmeetings.com/docs/authentication.md", "https://coldmeetings.com/docs/errors.md", "https://coldmeetings.com/docs/quickstart.md"] --- # API reference > **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. Every ColdMeetings API operation in seven resource groups, generated from the API OpenAPI document, with request fields, responses and errors. The ColdMeetings API has 25 operations in 7 groups. This reference is generated from the API's own OpenAPI document, so it lists exactly the routes the API registers. The machine readable copy is at [https://coldmeetings.com/openapi.json](https://coldmeetings.com/openapi.json). > Integrations that need credentials answer 503 `provider_unavailable` when the outside service cannot be reached. ## Base URL `YOUR_API_BASE_URL`. Paths below start with `/v1`, except `/health` and `/plans`. ## Authentication 23 of the 25 operations need an API key sent as `Authorization: Bearer cm_live_...`. The others are public. See [Authentication](https://coldmeetings.com/docs/authentication.md). ## Requests and responses - Bodies are JSON. Send `Content-Type: application/json`. Bodies over 256 KiB are refused. - Field names are snake_case. Timestamps are ISO 8601 in UTC. - Every response carries an `X-Request-Id` header. Quote it when you contact support. - Authenticated requests are rate limited per key. See [Rate limits](https://coldmeetings.com/docs/rate-limits.md). - Errors share one envelope with a stable `code`. See [Errors](https://coldmeetings.com/docs/errors.md). ## Resource groups | Group | Operations | What it covers | | --- | --- | --- | | [Account](https://coldmeetings.com/docs/api/account.md) | 5 | Your account, its plan and its prospect credits, a full export of your data, plus the two public endpoints that need no key. | | [Domains](https://coldmeetings.com/docs/api/domains.md) | 4 | Sending domains. Register a domain you own, publish its records and check that they are live. Only mailboxes on a domain that passes the check may send. | | [Mailboxes](https://coldmeetings.com/docs/api/mailboxes.md) | 2 | Mailboxes on your sending domains, and how many messages they may send today. New mailboxes ramp up with real low volume sends. | | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md) | 9 | A campaign is a sequence of steps, a list of prospects and a status. This is where credits are spent: each imported prospect costs one. | | [Replies](https://coldmeetings.com/docs/api/replies.md) | 2 | Replies from prospects. An opt out is caught by a fixed rule before any model runs. A reply that asks for a meeting can be booked from here. | | [Events](https://coldmeetings.com/docs/api/events.md) | 1 | Delivery events. Bounces and complaints suppress the address at once, and enough complaints pause the campaign. | | [Suppressions](https://coldmeetings.com/docs/api/suppressions.md) | 2 | The do not contact list. Bounces, complaints and opt out replies land here by themselves. You can add an address too. | ## All operations | Method | Path | What it does | Key | Page | | --- | --- | --- | --- | --- | | GET | `/health` | Liveness check. | None | [Account](https://coldmeetings.com/docs/api/account.md#get-health) | | GET | `/plans` | The three plans. Prices are set and nothing is charged live. | None | [Account](https://coldmeetings.com/docs/api/account.md#get-plans) | | GET | `/v1/account` | Account, plan, credit balance, usage and keys. | Required | [Account](https://coldmeetings.com/docs/api/account.md#get-v1account) | | GET | `/v1/account/export` | Every row the account has, as one JSON document: profile, keys (by prefix), credit ledger, invoices, domains, mailboxes, campaigns, prospects, replies and the do-not-contact list. Secrets are left out. Three requests per account every ten minutes. | Required | [Account](https://coldmeetings.com/docs/api/account.md#get-v1accountexport) | | POST | `/v1/billing/checkout` | Start a hosted checkout session. The plan starts when the payment is confirmed. | Required | [Account](https://coldmeetings.com/docs/api/account.md#post-v1billingcheckout) | | GET | `/v1/domains` | List sending domains. | Required | [Domains](https://coldmeetings.com/docs/api/domains.md#get-v1domains) | | POST | `/v1/domains` | Register a sending domain you already own and get the DNS records it needs. | Required | [Domains](https://coldmeetings.com/docs/api/domains.md#post-v1domains) | | POST | `/v1/domains/{id}/dns` | Publish the required records to your DNS host (Cloudflare). 503 until configured. | Required | [Domains](https://coldmeetings.com/docs/api/domains.md#post-v1domainsiddns) | | POST | `/v1/domains/{id}/check-dns` | Check live DNS for SPF, DKIM and DMARC and mark the domain authenticated. | Required | [Domains](https://coldmeetings.com/docs/api/domains.md#post-v1domainsidcheck-dns) | | GET | `/v1/mailboxes` | List mailboxes and today's ramp-up send capacity. | Required | [Mailboxes](https://coldmeetings.com/docs/api/mailboxes.md#get-v1mailboxes) | | POST | `/v1/mailboxes` | Create a mailbox on a sending domain. 503 until configured. | Required | [Mailboxes](https://coldmeetings.com/docs/api/mailboxes.md#post-v1mailboxes) | | GET | `/v1/campaigns` | List campaigns. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#get-v1campaigns) | | POST | `/v1/campaigns` | Create a draft campaign with its sequence. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#post-v1campaigns) | | GET | `/v1/campaigns/{id}` | One campaign. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#get-v1campaignsid) | | POST | `/v1/campaigns/{id}/prospects` | Import prospects: dedupe, suppression, region gate, verification, one credit each. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#post-v1campaignsidprospects) | | GET | `/v1/campaigns/{id}/preflight` | Everything that still blocks launch. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#get-v1campaignsidpreflight) | | POST | `/v1/campaigns/{id}/launch` | Launch through the sending engine. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#post-v1campaignsidlaunch) | | POST | `/v1/campaigns/{id}/pause` | Pause a campaign. Always pauses locally, even when the engine is unreachable; an unconfirmed engine pause is retried until it succeeds. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#post-v1campaignsidpause) | | POST | `/v1/campaigns/{id}/resume` | Resume a campaign you paused. Runs the preflight, removes suppressed leads at the sending engine, then restarts it. Refused while the engine has not confirmed the pause (409), and for a campaign ColdMeetings paused itself (403). | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#post-v1campaignsidresume) | | GET | `/v1/campaigns/{id}/report` | Sent, bounce, complaint and reply rates, reply intents, meetings booked. | Required | [Campaigns](https://coldmeetings.com/docs/api/campaigns.md#get-v1campaignsidreport) | | POST | `/v1/events` | Record a sent, bounce or complaint event from the sending engine. Complaints suppress and can pause. | Required | [Events](https://coldmeetings.com/docs/api/events.md#post-v1events) | | POST | `/v1/replies` | Record a reply. Opt-outs are suppressed by a fixed rule before any AI runs. | Required | [Replies](https://coldmeetings.com/docs/api/replies.md#post-v1replies) | | POST | `/v1/replies/{id}/meeting` | Book a meeting for a reply through the booking calendar. 503 until configured. | Required | [Replies](https://coldmeetings.com/docs/api/replies.md#post-v1repliesidmeeting) | | GET | `/v1/suppressions` | The do-not-contact list. | Required | [Suppressions](https://coldmeetings.com/docs/api/suppressions.md#get-v1suppressions) | | POST | `/v1/suppressions` | Add an address to the do-not-contact list. | Required | [Suppressions](https://coldmeetings.com/docs/api/suppressions.md#post-v1suppressions) | ## Related - [Authentication](https://coldmeetings.com/docs/authentication.md) - [Errors](https://coldmeetings.com/docs/errors.md) - [Quickstart](https://coldmeetings.com/docs/quickstart.md)