Retrieve a draft
GET /v1/drafts/{draft_id}
Read as Markdown ↗GET /v1/drafts/{draft_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns the draft's metadata, from (the inbox's current address and sender name) and its full saved content, attachments included as base64. The content is what you saved: Cherami adds its "Sent via Cherami" line and uses the inbox's sender name at the time you send. For a submitted draft, read the sent message named by sent_message_id for what was sent and its outcome.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
draft_id | path | Yes | string | Cherami resource ID returned by the API. |
curl example
Supply CHERAMI_API_KEY privately.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/drafts/DRAFT_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
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,
"from": {
"address": "my-agent@cherami.to"
},
"content": {
"to": [],
"cc": [],
"bcc": [],
"subject": "Example",
"text": "Example",
"attachments": []
}
}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 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: DraftDetail
| 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 | |
from | Yes | Mailbox | |
content | Yes | DraftContent |
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: DraftContent
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
to | Yes | array of Mailbox | |
cc | Yes | array of Mailbox | |
bcc | Yes | array of Mailbox | |
subject | Yes | string | |
text | Yes | string | |
html | No | string | |
in_reply_to | No | string | Cherami resource ID. |
labels | No | array of string | |
attachments | Yes | array of StoredAttachment |
Schema: StoredAttachment
| 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}$ |
disposition | Yes | "attachment" or "inline" | |
contentId | No | string | Content-ID of an inline file carried over from a forwarded message. |
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. |