---
title: "Edit a draft"
method: PATCH
path: "/v1/drafts/{draft_id}"
tags: ["drafts"]
---

# Edit a draft

`PATCH /v1/drafts/{draft_id}`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/drafts/{draft_id}`
- Auth: HTTP bearer

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.

## Path parameters

- `draft_id` string, required

## Request body

- UpdateDraft
  - `to` Mailbox[]
    - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @.
    - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
  - `cc` Mailbox[]
    - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @.
    - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
  - `bcc` Mailbox[]
    - `address` string, required: Bare address such as alex@example.com: ASCII, at most 254 characters and 64 before the @.
    - `name` string: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
  - `subject` string: No control characters; at most 998 UTF-8 bytes.
  - `text` string: Plain-text body.
  - `html` string, nullable: HTML alternative, sent as supplied.
  - `attachments` AttachmentInput[], nullable: A supplied array replaces the draft's files; [] or null removes them. Omit it to keep them.
    - `filename` string, required: At most 255 UTF-8 bytes, without control characters, slashes or backslashes.
    - `type` string, required: MIME type without parameters.
    - `content` string, byte, required: The file's bytes as padded base64, without line breaks.
  - `in_reply_to` string, nullable: ID of a ready received message or an accepted sent message in this inbox that has a Message-ID header.
  - `labels` Label[]: Label names, case-sensitive; order and duplicates don't matter.

## Response `200`

Success.

- DraftMetadata
  - `id` string, required: Cherami resource ID.
  - `inbox_id` string, required: Cherami resource ID.
  - `state` 'draft' | 'submitted', required
  - `subject` string, required
  - `created_at` string, date-time, required: UTC timestamp with milliseconds.
  - `updated_at` string, date-time, required: UTC timestamp with milliseconds.
  - `sent_message_id` string, nullable, required: Cherami resource ID.

## Other responses

- `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.
- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `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.
- `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.
- `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.
- `415`: `unsupported_media_type`: Send `Content-Type: application/json`.
- `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.

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)