--- title: "Create a draft" method: POST path: "/v1/inboxes/{inbox_id}/drafts" tags: ["drafts"] --- # Create a draft `POST /v1/inboxes/{inbox_id}/drafts` ## Request - Base URL: `https://cherami.to` - URL: `https://cherami.to/v1/inboxes/{inbox_id}/drafts` - Auth: HTTP bearer Saves a message in the inbox to finish, review or [send](https://cherami.to/docs/api/drafts/send-draft) later. Saving uses no sending allowance. Every field is optional (`{}` saves an empty draft) and takes the formats and limits of [send](https://cherami.to/docs/api/sending/send-message); recipients, subject and text are checked when you send. Creation returns metadata only: [retrieve the draft](https://cherami.to/docs/api/drafts/get-draft) for its content. ### Prepare a reply or forward Set `source` to an `action` (`reply`, `reply-all` or `forward`) and a `message_id`, a ready received message or an accepted sent message in this inbox, to have Cherami fill in the draft once, at creation: - `reply` and `reply-all` save the recipients, subject and `in_reply_to` derived as for [reply](https://cherami.to/docs/api/sending/reply-message) and [reply-all](https://cherami.to/docs/api/sending/reply-all-message). Fields you supply override them, including an empty array or a null `in_reply_to`. Your `text` and `attachments` make up the reply; no history or original files are copied. The message you reply to must still exist when you send, and changing `in_reply_to` later doesn't re-derive recipients or subject. - `forward` saves the full forward as text and HTML, with your `text` as the note, plus the original attachments unless `source.include_attachments` is `false`. Add recipients now or later. `attachments` can't be supplied with a forward source; edit the draft afterwards to change its files. ### Recover creation Include an `idempotency_key` to make a retry safe. If creation is uncertain, repeat the exact request with the same key within 24 hours of your first attempt: a match returns `200` with `replayed: true` and the draft's current metadata, without applying the payload again. After 24 hours, or without a key, [list drafts](https://cherami.to/docs/api/drafts/list-drafts) with `state=all` before creating again: a blind repeat makes a duplicate. ## Path parameters - `inbox_id` string, required ## Request body - CreateDraft - `to` Mailbox[] - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. - `cc` Mailbox[] - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. - `bcc` Mailbox[] - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. - `subject` string: No control characters; at most 998 UTF-8 bytes. - `text` string: Plain-text body. - `html` string, nullable: HTML alternative, sent as supplied. - `attachments` AttachmentInput[], nullable: Omitted, null or [] means no attachments. - `filename` string, required: At most 255 UTF-8 bytes, without control characters, slashes or backslashes. - `type` string, required: MIME type without parameters. - `content` string, byte, required: The file's bytes as padded base64, without line breaks. - `in_reply_to` string, nullable: ID of a ready received message or an accepted sent message in this inbox that has a Message-ID header. - `labels` Label[]: Label names, case-sensitive; order and duplicates don't matter. - `idempotency_key` string: Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again. - `source` union: Fills in the draft once, at creation, as a reply, reply-all or forward of message_id. - object - `action` 'reply' | 'reply-all', required - `message_id` string, required: ID of a ready received message or an accepted sent message in this inbox. - object - `action` 'forward', required - `message_id` string, required: ID of a ready received message or an accepted sent message in this inbox. - `include_attachments` boolean: false leaves out every original file, embedded images included. ## 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 - `id` string, required: Cherami resource ID. - `inbox_id` string, required: Cherami resource ID. - `state` 'draft' | 'submitted', required - `subject` string, required - `created_at` string, date-time, required: UTC timestamp with milliseconds. - `updated_at` string, date-time, required: UTC timestamp with milliseconds. - `sent_message_id` string, nullable, required: Cherami resource ID. - `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, required: When the key stops protecting retries. ## Other responses - `201`: Created. - `400`: `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_draft`: Correct the draft field, `source` or listing parameter the message names. `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. - `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). - `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`: `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. `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_recipients_unavailable`: No recipients remain once the sending inbox is excluded. Send a new message to recipients the task authorizes. - `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`. - `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)