--- title: "API reference: Replies" url: "https://coldmeetings.com/docs/api/replies.md" canonical_url: "https://coldmeetings.com/docs/api/replies" last_updated: "2026-10-23" type: "reference" summary: "Record prospect replies, let a fixed rule suppress opt outs before any model runs, classify intent and book a meeting with the ColdMeetings API." related: ["https://coldmeetings.com/docs/api.md", "https://coldmeetings.com/docs/errors.md"] --- # API reference: Replies > **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. Record prospect replies, let a fixed rule suppress opt outs before any model runs, classify intent and book a meeting with the ColdMeetings API. 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. 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/replies`](#post-v1replies) | Record a reply. Opt-outs are suppressed by a fixed rule before any AI runs. | | [`POST /v1/replies/{id}/meeting`](#post-v1repliesidmeeting) | Book a meeting for a reply through the booking calendar. 503 until configured. | ## POST /v1/replies Record a reply. Opt-outs are suppressed by a fixed rule before any AI runs. A fixed rule looks for opt-out wording first. If it matches, the intent is `opt_out`, the address is suppressed, and no model runs. 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. | | `subject` | string | Yes | Up to 300 characters. | | `body` | string | Yes | Up to 20000 characters. | Example body: ```json { "campaign_id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd", "email": "jordan@northwind.example", "subject": "Re: Outbound without the busywork", "body": "Sounds useful. Can we talk Thursday?" } ``` ### Response Status 201 Created. ```json { "reply_id": "rpl_Vw3ZbN1pEs9fKd2LmQx7Rt", "intent": "interested", "classified_by": "ai", "suppressed": false } ``` - `intent` is one of `interested`, `not_interested`, `out_of_office`, `opt_out`, `question` or `other`, or `null` when classification is unavailable. - `classified_by` is `rule`, `ai` or `unavailable`. When it is `unavailable`, a `classification_note` explains why and the reply is still stored. ### 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/replies \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "campaign_id": "cmp_2LmQx7RtVw3ZbN1pEs9fKd", "email": "jordan@northwind.example", "subject": "Re: Outbound without the busywork", "body": "Sounds useful. Can we talk Thursday?" }' ``` ## POST /v1/replies/{id}/meeting Book a meeting for a reply through the booking calendar. 503 until configured. Books a meeting with the person who sent the reply. The attendee email is taken from the reply. Authentication: send your API key as a bearer token. See [Authentication](https://coldmeetings.com/docs/authentication.md). > This operation answers 503 `provider_unavailable` when its outside service cannot be reached. The booking calendar could not be reached. Nothing is simulated and nothing is charged. ### Path parameters | Name | Type | Notes | | --- | --- | --- | | `id` | string | Id of the reply. | ### Request body Send a JSON object. | Field | Type | Required | Notes | | --- | --- | --- | --- | | `attendee_name` | string | Yes | Up to 120 characters. | | `starts_at` | string | Yes | Format: date-time. | | `timezone` | string | Yes | At least 3 characters. Up to 64 characters. | Example body: ```json { "attendee_name": "Jordan Lee", "starts_at": "2026-10-22T15:00:00Z", "timezone": "America/New_York" } ``` ### Response Status 201 Created. ```json { "booking_id": "bk_5Qw8Lm2Zx" } ``` ### 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: The address is on the do-not-contact list, a meeting is already booked for this reply, or the body is invalid. 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 reply on this account. - [`provider_unavailable`](https://coldmeetings.com/docs/errors.md#provider_unavailable), HTTP 503: The booking calendar could not be reached. - [`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/replies/rpl_Vw3ZbN1pEs9fKd2LmQx7Rt/meeting \ -H "Authorization: Bearer $COLDMEETINGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "attendee_name": "Jordan Lee", "starts_at": "2026-10-22T15:00:00Z", "timezone": "America/New_York" }' ``` ## Related - [API reference](https://coldmeetings.com/docs/api.md) - [Errors](https://coldmeetings.com/docs/errors.md)