# Send a draft

POST /v1/drafts/{draft_id}/send

Source: https://cherami.to/docs/api/drafts/send-draft



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`POST /v1/drafts/{draft_id}/send`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Sends the draft's current saved content. Send `{}`.

The first send attempt freezes the draft as `submitted`, with `sent_message_id` naming the sent message, whatever the outcome: `rejected` and `unknown` included. A submitted draft can't be edited or sent again. Create a new draft for a deliberate new attempt, not to resolve an `unknown` outcome. A refusal before sending (invalid content, a blocked recipient, no allowance) leaves the draft editable.

The response is an ordinary [send receipt](https://cherami.to/docs/api/sending/send-message#response-and-outcomes). If it is lost or uncertain, repeat this request at any time: it returns the original attempt with `replayed: true` and never sends again.

## Parameters [#parameters]

| Parameter  | Location | Required | Type   | Meaning                                  |
| ---------- | -------- | -------- | ------ | ---------------------------------------- |
| `draft_id` | path     | Yes      | string | Cherami resource ID returned by the API. |

## Request body [#request-body]

JSON object, at most 4 KiB in total.

### Schema: SendDraft [#schema-senddraft]

| Field             | Required | Type   | Meaning and constraints                                                                                |
| ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `idempotency_key` | No       | string | Not needed: the draft ID already makes a repeat safe, at any time. `pattern`: `^[A-Za-z0-9_-]{1,128}$` |

Unknown fields are rejected.

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

Save the payload as `request.json`.

```json
{}
```

```sh
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/drafts/DRAFT_ID/send" \
  --header "Authorization: Bearer $CHERAMI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

## Responses [#responses]

### HTTP 200 [#http-200]

A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1]

[SendReceipt](#schema-sendreceipt)

### Part 2 [#part-2]

| Field      | Required | Type   | Meaning and constraints |
| ---------- | -------- | ------ | ----------------------- |
| `replayed` | Yes      | `true` |                         |

```json
{
  "limited": false,
  "message": {
    "id": "33333333-3333-4333-8333-333333333333",
    "inbox_id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-10-01T00:00:00.000Z",
    "recipient_count": 1,
    "status": "unknown",
    "provider_message_id": null,
    "error_code": null,
    "thread_id": "44444444-4444-4444-8444-444444444444",
    "in_reply_to": null,
    "labels": []
  },
  "outcome_persisted": true,
  "replayed": true
}
```

### HTTP 201 [#http-201]

Attempt recorded; check message.status.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1-1]

[SendReceipt](#schema-sendreceipt)

### Part 2 [#part-2-1]

| Field      | Required | Type    | Meaning and constraints |
| ---------- | -------- | ------- | ----------------------- |
| `replayed` | No       | `false` |                         |

### HTTP 400 [#http-400]

`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.

`invalid_message`: Correct the recipients, subject, body, `in_reply_to`, attachments or reply and forward fields as the message describes.

`invalid_name`: Use plain text without control characters, at most 256 UTF-8 bytes after trimming. The message names the field.

`invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.

`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.

`invalid_draft`: Correct the draft field, `source` or listing parameter the message names.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`operation_not_allowed`: Sending, or deletion and restore, is turned off for this account; the message says which. Contact [hello@cherami.to](mailto:hello@cherami.to).

`recipient_not_allowed`: Nothing was sent: the inbox's [sending rules](https://cherami.to/account/sending-rules) block one or more recipients, which the message lists. Use allowed recipients, or ask the account owner to allow them; do not send through another inbox to get around the rules.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 409 [#http-409]

`reply_not_ready`: The source cannot be replied to or forwarded yet. A received message must have `processing_status` `ready`; a sent message must have `status` `accepted`.

`reply_headers_unavailable`: The target has no usable Message-ID to reply to. Send a new message without `in_reply_to`.

`idempotency_conflict`: The key was first used with different input. To recover that request, repeat it with its original inbox and payload; a different request needs its own key.

`idempotency_result_unavailable`: The key already created an inbox, draft or send whose result has since been deleted. Nothing new was created or sent; do not repeat the request under a new key. If a sent message is still in Trash, restore it to read the outcome.

`draft_busy`: Another change to this draft landed first. Read the draft, then repeat the edit or send if it still applies.

`draft_result_unavailable`: The draft was already submitted and its sent message has since been deleted; nothing was sent again. If that message is still in Trash, restore it with the draft's `sent_message_id` to read the outcome.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 413 [#http-413]

`body_too_large`: Reduce the JSON request to the operation's body limit.

`message_too_large`: The message exceeds 5 MiB counting text, HTML and base64 attachment content, or a forwarded original has more than 32 attachments. Reduce the content or attachments; for a forward, set `include_attachments` to false or attach selected files to a new message.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

`unsupported_media_type`: Send `Content-Type: application/json`.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 429 [#http-429]

`outbound_limit_reached`: The rolling 24-hour sending allowance cannot cover this message, at one charge per recipient. With `reason` `temporary_exhaustion`, retry at `sufficient_capacity_at`; with `message_exceeds_allowance`, the message needs more than the whole allowance: reduce its recipients or [request a higher allowance](https://cherami.to/docs/guides/support). See [sending allowance](https://cherami.to/docs/api/sending/get-outbound-quota).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Retry-After`: Seconds to wait before retrying. For sending allowance it matches sufficient\_capacity\_at.

Content type: `application/json`.

[QuotaError](#schema-quotaerror)

### HTTP 503 [#http-503]

`content_unavailable`: Stored content could not be read. Retry later.

`draft_unavailable`: The draft request failed. Repeat a draft send with the same draft ID: it never sends twice. Repeat a creation with its original idempotency key and payload; without a key, list drafts first. Read the draft before repeating an edit. Retry a read or a deletion.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: SendReceipt [#schema-sendreceipt]

accepted in message.status means the provider took the message, not that it was delivered.

| Field                    | Required | Type                                 | Meaning and constraints                                                                                                 |
| ------------------------ | -------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `limited`                | Yes      | `false`                              |                                                                                                                         |
| `message`                | Yes      | [SentMetadata](#schema-sentmetadata) |                                                                                                                         |
| `outcome_persisted`      | Yes      | boolean                              | false: this response is the only record of the outcome; keep it rather than resending.                                  |
| `replayed`               | No       | boolean                              | true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.        |
| `idempotency_expires_at` | No       | string                               | When the key stops protecting retries. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

## Schema: SentMetadata [#schema-sentmetadata]

| Field                 | Required | Type                                        | Meaning and constraints                                                                                           |
| --------------------- | -------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                  | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `inbox_id`            | Yes      | string                                      | Cherami resource ID.                                                                                              |
| `created_at`          | Yes      | string                                      | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |
| `recipient_count`     | Yes      | integer                                     | `minimum`: `0`                                                                                                    |
| `status`              | Yes      | `"accepted"` or `"rejected"` or `"unknown"` |                                                                                                                   |
| `provider_message_id` | Yes      | string or null                              | Message-ID the provider assigned when it accepted the message.                                                    |
| `error_code`          | Yes      | string or null                              | Reason code for a rejected or unknown outcome, such as E\_RECIPIENT\_SUPPRESSED or acceptance\_unknown.           |
| `thread_id`           | Yes      | string or null                              |                                                                                                                   |
| `in_reply_to`         | Yes      | string or null                              |                                                                                                                   |
| `labels`              | Yes      | array of string                             |                                                                                                                   |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

## Schema: QuotaError [#schema-quotaerror]

| Field                    | Required | Type                                                      | Meaning and constraints                                                                                                                                                          |
| ------------------------ | -------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error`                  | Yes      | object                                                    |                                                                                                                                                                                  |
| `quota`                  | Yes      | [Quota](#schema-quota)                                    |                                                                                                                                                                                  |
| `requested_recipients`   | Yes      | integer                                                   | Recipients this message needs, one per To, Cc and Bcc entry. `minimum`: `0`                                                                                                      |
| `reason`                 | Yes      | `"temporary_exhaustion"` or `"message_exceeds_allowance"` | temporary\_exhaustion: enough capacity returns at sufficient\_capacity\_at. message\_exceeds\_allowance: the message needs more than the whole allowance, so waiting won't help. |
| `sufficient_capacity_at` | Yes      | string or null                                            | When this message will fit; null with message\_exceeds\_allowance.                                                                                                               |
| `guidance`               | Yes      | string                                                    | What keeps working while sending is limited.                                                                                                                                     |

### `error` fields [#error-fields-1]

| Field     | Required | Type                       | Meaning and constraints |
| --------- | -------- | -------------------------- | ----------------------- |
| `code`    | Yes      | `"outbound_limit_reached"` |                         |
| `message` | Yes      | string                     |                         |

## Schema: Quota [#schema-quota]

| Field                  | Required | Type                     | Meaning and constraints                                                |
| ---------------------- | -------- | ------------------------ | ---------------------------------------------------------------------- |
| `allowance`            | Yes      | integer                  | Recipients the account can send to in any 24 hours. `minimum`: `0`     |
| `used`                 | Yes      | integer                  | Recipients charged in the last 24 hours. `minimum`: `0`                |
| `remaining`            | Yes      | integer                  | Recipients you can send to now. `minimum`: `0`                         |
| `next_capacity_at`     | Yes      | string or null           | When the next units return; null when nothing is charged.              |
| `next_capacity_amount` | Yes      | integer                  | Recipients that become available at next\_capacity\_at. `minimum`: `0` |
| `window_hours`         | Yes      | `24`                     |                                                                        |
| `unit`                 | Yes      | `"recipient_deliveries"` | One unit per To, Cc or Bcc recipient.                                  |
| `increase_request`     | Yes      | string                   | How to ask for a larger allowance.                                     |
| `policy_url`           | Yes      | string                   |                                                                        |

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
