Edit a draft
PATCH /v1/drafts/{draft_id}
Read as Markdown ↗PATCH /v1/drafts/{draft_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Supply at least one editable creation field, excluding source and idempotency_key. Only supplied fields change. Recipient arrays, attachments and labels replace their entire respective lists. When revising text, revise or clear html separately if needed; Cherami does not synchronize the alternatives. New attachment inputs use the ordinary three-field format, not service-generated inline metadata.
Successful edits return 200 with draft metadata. Concurrent edits to different fields preserve both changes; the last saved value wins for the same field. No version parameter or review lock is supported. Repeated contention can return 409 draft_busy; retrieve current content before editing again. After an uncertain acknowledgement, also retrieve before repeating an edit that might overwrite another agent's work.
Submitted drafts return 409 draft_submitted and cannot be edited or returned to draft.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
draft_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
Request body
JSON object. Total UTF-8 request body limit: 8388608 bytes.
Schema: UpdateDraft
Only supplied fields change; arrays replace their entire lists. No source, version, review lock or idempotency key. Submitted drafts cannot be edited.
| 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 | |
attachments | No | array of AttachmentInput or null | Omitted or null means no attachments; an empty array also clears draft attachments. |
in_reply_to | No | string or null | |
labels | No | array of Label | Trimmed, deduplicated and case-sensitive. Order is not significant. maxItems: 32 |
Unknown fields are rejected.
At least 1 field must be supplied.
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
Save the intended payload as a private request.json file and replace illustrative values. For an uncertain response, follow the operation-specific recovery rules.
{
"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
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
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: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.
invalid_message: Correct the send fields, recipients, reply ID, or attachments using the message's guidance.
invalid_name: Correct the inbox, sender or recipient display name using the returned guidance.
invalid_labels: Correct label names, changes, filter groups, or discovery prefix.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 409
draft_busy: An edit/send raced other changes. Retrieve current content before trying again.
draft_submitted: Submitted drafts cannot be edited or returned to draft. Retrieve the linked sent message.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 413
body_too_large: Reduce the JSON request to the endpoint's body limit.
message_too_large: Reduce message content and attachments. Passing local checks does not guarantee generated MIME fits the provider limit.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 415
unsupported_media_type: Send Content-Type: application/json.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 503
content_unavailable: Expected stored content is unavailable. Retry the read later.
draft_unavailable: Draft operation is uncertain. Follow draft-specific recovery; do not blindly create a replacement.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: DraftMetadata
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
inbox_id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
state | Yes | "draft" or "submitted" | |
subject | Yes | string | |
created_at | Yes | string | UTC service instant with milliseconds and Z suffix. 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 service instant with milliseconds and Z suffix. 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 | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
Schema: Mailbox
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
address | Yes | string | Bare ASCII address, at most 254 characters, local part at most 64. No display-name header syntax. maxLength: 254 |
name | No | string | Unicode name, trimmed; blank means unnamed. No control characters. At most 256 UTF-8 bytes after trimming. x-max-utf8-bytes: 256 |
Unknown fields are rejected.
Schema: AttachmentInput
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
filename | Yes | string | Nonempty, no control characters, slash or backslash. At most 255 UTF-8 bytes. 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 | Padded base64 original bytes, no whitespace; encoded length must be a multiple of four. Empty files are accepted. contentEncoding: base64 pattern: ^[A-Za-z0-9+/]*={0,2}$ |
Unknown fields are rejected.
Schema: Label
1–128 UTF-8 bytes after trimming. Well-formed Unicode without control characters; case-sensitive.
string. x-max-utf8-bytes: 128
HTTP conventions, errors and pagination · Download OpenAPI 3.1