Edit a draft
PATCH /v1/drafts/{draft_id}
Read as Markdown ↗PATCH /v1/drafts/{draft_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Changes only the fields you supply; a list you supply (recipients, attachments, labels) replaces the whole list. text and html are separate bodies: when you change one, update the other or clear it with html: null. source and idempotency_key can't be edited.
Supply attachments with only filename, type and content, even when reusing files read from the draft.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
draft_id | path | Yes | string | Cherami resource ID returned by the API. |
Request body
JSON object, at most 8 MiB in total.
Schema: UpdateDraft
| 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 | A supplied array replaces the draft's files; [] or null removes them. Omit it to keep them. |
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 |
Unknown fields are rejected.
At least 1 field must be supplied.
curl example
Supply CHERAMI_API_KEY privately.
Save the payload as request.json, replacing the example values.
{
"text": "Revised proposal.",
"html": null
}curl --silent --show-error --include --request PATCH \
"https://cherami.to/v1/drafts/DRAFT_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
HTTP 200
Success.
X-Request-ID: Identifies this request; include it when reporting a problem.
Content type: application/json.
{
"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
}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.
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
draft_busy: Another change to this draft landed first. Read the draft, then repeat the edit or send if it still applies.
draft_submitted: The draft's content froze on its first send attempt, so it cannot be edited. Read the sent message named by the draft's sent_message_id for the outcome; to send different content, create a new draft.
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: DraftMetadata
| 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 |
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