cherami.
API referenceSaved drafts

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

ParameterLocationRequiredTypeMeaning
draft_idpathYesstringCherami resource ID returned by the API.

Request body

JSON object, at most 8 MiB in total.

Schema: UpdateDraft

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 nullA supplied array replaces the draft's files; [] or null removes them. Omit it to keep them.
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

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.json

Responses

HTTP 200

Success.

  • X-Request-ID: Identifies this request; include it when reporting a problem.

Content type: application/json.

DraftMetadata

{
  "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.

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

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.

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

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

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