--- title: "Send a draft" method: POST path: "/v1/drafts/{draft_id}/send" tags: ["drafts"] --- # Send a draft `POST /v1/drafts/{draft_id}/send` ## Request - Base URL: `https://cherami.to` - URL: `https://cherami.to/v1/drafts/{draft_id}/send` - Auth: HTTP bearer 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. ## Path parameters - `draft_id` string, required ## Request body - SendDraft - `idempotency_key` string: Not needed: the draft ID already makes a repeat safe, at any time. ## Response `200` A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent. - object: accepted in message.status means the provider took the message, not that it was delivered. - `limited` unknown, required - `message` SentMetadata, required - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `created_at` string, date-time, required: UTC timestamp with milliseconds. - `recipient_count` integer, required - `status` 'accepted' | 'rejected' | 'unknown', required - `provider_message_id` string, nullable, required: Message-ID the provider assigned when it accepted the message. - `error_code` string, nullable, required: Reason code for a rejected or unknown outcome, such as E_RECIPIENT_SUPPRESSED or acceptance_unknown. - `thread_id` string, nullable, required: Cherami resource ID. - `in_reply_to` string, nullable, required: Cherami resource ID. - `labels` string[], required - `outcome_persisted` boolean, required: false: this response is the only record of the outcome; keep it rather than resending. - `replayed` true, required: true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent. - `idempotency_expires_at` string, date-time: When the key stops protecting retries. ## Other responses - `201`: Attempt recorded; check message.status. - `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. - `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer `. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery). - `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](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. - `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. - `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. - `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. - `415`: `unsupported_media_type`: Send `Content-Type: application/json`. - `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). - `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. --- [API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)