Create a draft
POST /v1/inboxes/{inbox_id}/drafts
Read as Markdown ↗POST /v1/inboxes/{inbox_id}/drafts
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Saves a message in the inbox to finish, review or send later. Saving uses no sending allowance. Every field is optional ({} saves an empty draft) and takes the formats and limits of send; recipients, subject and text are checked when you send. Creation returns metadata only: retrieve the 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:
replyandreply-allsave the recipients, subject andin_reply_toderived as for reply and reply-all. Fields you supply override them, including an empty array or a nullin_reply_to. Yourtextandattachmentsmake up the reply; no history or original files are copied. The message you reply to must still exist when you send, and changingin_reply_tolater doesn't re-derive recipients or subject.forwardsaves the full forward as text and HTML, with yourtextas the note, plus the original attachments unlesssource.include_attachmentsisfalse. Add recipients now or later.attachmentscan'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 with state=all before creating again: a blind repeat makes a duplicate.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 8 MiB in total.
Schema: CreateDraft
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
to | No | array of Mailbox | maxItems: 50 |
cc | No | array of Mailbox | maxItems: 50 |
bcc | No | array of Mailbox | maxItems: 50 |
subject | No | string | No control characters; at most 998 UTF-8 bytes. x-max-utf8-bytes: 998 |
text | No | string | Plain-text body. |
html | No | string or null | HTML alternative, sent as supplied; null means none. |
attachments | No | array of AttachmentInput or null | Omitted, null or [] means no attachments. |
in_reply_to | No | string or null | ID of a ready received message or an accepted sent message in this inbox that has a Message-ID header; null means none. |
labels | No | array of Label | Label names, case-sensitive; order and duplicates don't matter. maxItems: 32 |
idempotency_key | No | 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. pattern: ^[A-Za-z0-9_-]{1,128}$ |
source | No | object or object | Fills in the draft once, at creation, as a reply, reply-all or forward of message_id. |
Unknown fields are rejected.
source fields
Fills in the draft once, at creation, as a reply, reply-all or forward of message_id.
Exactly one of these shapes applies.
Alternative 1
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
action | Yes | "reply" or "reply-all" | |
message_id | Yes | string | ID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$ |
Unknown fields are rejected.
Alternative 2
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
action | Yes | "forward" | |
message_id | Yes | string | ID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$ |
include_attachments | No | boolean | false leaves out every original file, embedded images included. default: true |
Unknown fields are rejected.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"subject": "Proposal for review",
"text": "Draft proposal.",
"idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY"
}curl --silent --show-error --include --request POST \
"https://cherami.to/v1/inboxes/INBOX_ID/drafts" \
--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 | |
idempotency_expires_at | Yes | 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$ |
{
"id": "11111111-1111-4111-8111-111111111111",
"inbox_id": "11111111-1111-4111-8111-111111111111",
"state": "draft",
"subject": "Example",
"created_at": "2026-10-01T00:00:00.000Z",
"updated_at": "2026-10-01T00:00:00.000Z",
"sent_message_id": null,
"replayed": true,
"idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}HTTP 201
Created.
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_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.
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 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
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.
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 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: CreatedDraft
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID. |
inbox_id | Yes | string | Cherami resource ID. |
state | Yes | "draft" or "submitted" | |
subject | Yes | string | |
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$ |
updated_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$ |
sent_message_id | Yes | string or null | |
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: 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: Mailbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
address | Yes | string | Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254 |
name | No | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. x-max-utf8-bytes: 256 |
Unknown fields are rejected.
Schema: AttachmentInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
filename | Yes | string | At most 255 UTF-8 bytes, without control characters, slashes or backslashes. minLength: 1 x-max-utf8-bytes: 255 |
type | Yes | string | MIME type without parameters. maxLength: 127 pattern: ^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$ |
content | Yes | string | The file's bytes as padded base64, without line breaks. contentEncoding: base64 pattern: ^[A-Za-z0-9+/]*={0,2}$ |
Unknown fields are rejected.
Schema: Label
1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
string. x-max-utf8-bytes: 128