Retrieve a draft
GET /v1/drafts/{draft_id}
Read as Markdown ↗GET /v1/drafts/{draft_id}
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns metadata plus from and content. from is the inbox's current address and optional sender name. content contains full to, cc, bcc, subject, text, attachments, optional html, in_reply_to and nonempty labels. Attachment objects include filename, type, base64 content, and disposition; source-derived inline files also have contentId. Bodies are not extracted or truncated.
The content is the saved draft, before Cherami's outgoing attribution. Sending uses current sender settings and appends attribution then. For a submitted draft, retrieve sent_message_id through the sent-message endpoint for the actual sender snapshot, attributed content and outcome. Draft retrieval alone is not approval and does not lock the content.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
draft_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/drafts/DRAFT_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
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,
"from": {
"address": "my-agent@cherami.to"
},
"content": {
"to": [],
"cc": [],
"bcc": [],
"subject": "Example",
"text": "Example",
"attachments": []
}
}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 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: DraftDetail
| 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 | |
from | Yes | Mailbox | |
content | Yes | DraftContent |
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: 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, distinct from the RFC Message-ID. Use the returned value. |
labels | No | array of string | |
attachments | Yes | array of StoredAttachment |
Schema: StoredAttachment
| 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}$ |
disposition | Yes | "attachment" or "inline" | |
contentId | No | string | Present for source-derived inline files. |
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. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1