List drafts
GET /v1/inboxes/{inbox_id}/drafts
Read as Markdown ↗GET /v1/inboxes/{inbox_id}/drafts
Requires a Claim-issued API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns 200 with {"drafts":[...],"next_cursor":null}. Entries contain draft metadata without creation-key fields. state is draft (default), submitted or all. Results are newest-created first. limit is 1–100, default 20; use the returned opaque cursor with the same inbox and state. This is a live listing, not a snapshot. Drafts do not appear in received/sent mail search or conversations before submission.
Unsupported or repeated query parameters and malformed or mismatched cursors return 400 invalid_draft; an invalid limit returns 400 invalid_limit.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
inbox_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
limit | query | No | integer | Decimal integer without signs, whitespace or leading zeroes. minimum: 1 maximum: 100 default: 20 |
cursor | query | No | string | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next_cursor is null. |
state | query | No | "draft" or "submitted" or "all" | Include submitted drafts when reconciling uncertain creation. Only limit, cursor and state are accepted, each once. default: draft |
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/inboxes/INBOX_ID/drafts" \
--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.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
drafts | Yes | array of DraftMetadata | |
next_cursor | Yes | string or null |
{
"drafts": [],
"next_cursor": null
}HTTP 400
invalid_limit: Use an integer from 1 to 100.
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.
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 503
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. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1