cherami.
API referenceSaved drafts

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:

  • reply and reply-all save the recipients, subject and in_reply_to derived as for reply and reply-all. 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 with state=all before creating again: a blind repeat makes a duplicate.

Parameters

ParameterLocationRequiredTypeMeaning
inbox_idpathYesstringCherami resource ID returned by the API.

Request body

JSON object, at most 8 MiB in total.

Schema: CreateDraft

FieldRequiredTypeMeaning and constraints
toNoarray of MailboxmaxItems: 50
ccNoarray of MailboxmaxItems: 50
bccNoarray of MailboxmaxItems: 50
subjectNostringNo control characters; at most 998 UTF-8 bytes. x-max-utf8-bytes: 998
textNostringPlain-text body.
htmlNostring or nullHTML alternative, sent as supplied; null means none.
attachmentsNoarray of AttachmentInput or nullOmitted, null or [] means no attachments.
in_reply_toNostring or nullID of a ready received message or an accepted sent message in this inbox that has a Message-ID header; null means none.
labelsNoarray of LabelLabel names, case-sensitive; order and duplicates don't matter. maxItems: 32
idempotency_keyNostringYour 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}$
sourceNoobject or objectFills 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
FieldRequiredTypeMeaning and constraints
actionYes"reply" or "reply-all"
message_idYesstringID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$

Unknown fields are rejected.

Alternative 2
FieldRequiredTypeMeaning and constraints
actionYes"forward"
message_idYesstringID of a ready received message or an accepted sent message in this inbox. pattern: ^[a-f0-9-]{36}$
include_attachmentsNobooleanfalse 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.json

Responses

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

CreatedDraft

Part 2

FieldRequiredTypeMeaning and constraints
replayedYestrue
idempotency_expires_atYesstringWhen 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

CreatedDraft

Part 2

FieldRequiredTypeMeaning and constraints
replayedNofalse

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.

Error

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.

Error

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

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.

Error

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

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

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: CreatedDraft

FieldRequiredTypeMeaning and constraints
idYesstringCherami resource ID.
inbox_idYesstringCherami resource ID.
stateYes"draft" or "submitted"
subjectYesstring
created_atYesstringUTC timestamp with milliseconds. format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
updated_atYesstringUTC 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_idYesstring or null
replayedNobooleantrue when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.
idempotency_expires_atNostringWhen 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

FieldRequiredTypeMeaning and constraints
errorYesobject

error fields

FieldRequiredTypeMeaning and constraints
codeYesstringCode to handle. Handle a code you don't recognize by its HTTP status.
messageYesstringExplanation of this case; its wording can change.

Schema: Mailbox

FieldRequiredTypeMeaning and constraints
addressYesstringBare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @. maxLength: 254
nameNostringOptional 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

FieldRequiredTypeMeaning and constraints
filenameYesstringAt most 255 UTF-8 bytes, without control characters, slashes or backslashes. minLength: 1 x-max-utf8-bytes: 255
typeYesstringMIME type without parameters. maxLength: 127 pattern: ^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$
contentYesstringThe 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

Errors, limits and pagination · Download OpenAPI 3.1

On this page