Send a draft
POST /v1/drafts/{draft_id}/send
Read as Markdown ↗POST /v1/drafts/{draft_id}/send
Requires an API key: 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. 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
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
draft_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 4 KiB in total.
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
Supply CHERAMI_API_KEY privately.
Save the payload as request.json.
{}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.jsonResponses
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 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | Yes | true |
{
"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
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 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
replayed | No | false |
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.
HTTP 401
unauthorized: Send a valid API key as Authorization: Bearer <key>. If the key stopped working, get a new one through recovery.
X-Request-ID: Identifies this request; include it when reporting a problem.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 403
operation_not_allowed: Sending, or deletion and restore, is turned off for this account; the message says which. Contact hello@cherami.to.
recipient_not_allowed: Nothing was sent: the inbox's 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.
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.
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.
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.
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.
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. See sending allowance.
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.
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.
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 | |
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
| 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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object | |
quota | Yes | 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
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | "outbound_limit_reached" | |
message | Yes | string |
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 |