API reference
Open as markdownFor AI agents: the docs index is at /llms.txt, and every page is also served as markdown at its URL plus .md.
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.
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.
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-Idheader. Quote it when you contact support. - Authenticated requests are rate limited per key. See Rate limits.
- Errors share one envelope with a stable
code. See Errors.
Resource groups#
| Group | Operations | What it covers |
|---|---|---|
| Account | 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 | 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 | 2 | Mailboxes on your sending domains, and how many messages they may send today. New mailboxes ramp up with real low volume sends. |
| Campaigns | 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 | 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 | 1 | Delivery events. Bounces and complaints suppress the address at once, and enough complaints pause the campaign. |
| Suppressions | 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 |
| GET | /plans | The three plans. Prices are set and nothing is charged live. | None | Account |
| GET | /v1/account | Account, plan, credit balance, usage and keys. | Required | Account |
| 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 |
| POST | /v1/billing/checkout | Start a hosted checkout session. The plan starts when the payment is confirmed. | Required | Account |
| GET | /v1/domains | List sending domains. | Required | Domains |
| POST | /v1/domains | Register a sending domain you already own and get the DNS records it needs. | Required | Domains |
| POST | /v1/domains/{id}/dns | Publish the required records to your DNS host (Cloudflare). 503 until configured. | Required | Domains |
| POST | /v1/domains/{id}/check-dns | Check live DNS for SPF, DKIM and DMARC and mark the domain authenticated. | Required | Domains |
| GET | /v1/mailboxes | List mailboxes and today's ramp-up send capacity. | Required | Mailboxes |
| POST | /v1/mailboxes | Create a mailbox on a sending domain. 503 until configured. | Required | Mailboxes |
| GET | /v1/campaigns | List campaigns. | Required | Campaigns |
| POST | /v1/campaigns | Create a draft campaign with its sequence. | Required | Campaigns |
| GET | /v1/campaigns/{id} | One campaign. | Required | Campaigns |
| POST | /v1/campaigns/{id}/prospects | Import prospects: dedupe, suppression, region gate, verification, one credit each. | Required | Campaigns |
| GET | /v1/campaigns/{id}/preflight | Everything that still blocks launch. | Required | Campaigns |
| POST | /v1/campaigns/{id}/launch | Launch through the sending engine. | Required | Campaigns |
| 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 |
| 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 |
| GET | /v1/campaigns/{id}/report | Sent, bounce, complaint and reply rates, reply intents, meetings booked. | Required | Campaigns |
| POST | /v1/events | Record a sent, bounce or complaint event from the sending engine. Complaints suppress and can pause. | Required | Events |
| POST | /v1/replies | Record a reply. Opt-outs are suppressed by a fixed rule before any AI runs. | Required | Replies |
| POST | /v1/replies/{id}/meeting | Book a meeting for a reply through the booking calendar. 503 until configured. | Required | Replies |
| GET | /v1/suppressions | The do-not-contact list. | Required | Suppressions |
| POST | /v1/suppressions | Add an address to the do-not-contact list. | Required | Suppressions |