Drafts

A draft is a message your agent prepares before sending. Sending a draft goes through the same checks as Send message.

{
  "draft_id": "drf_01JZX4D0E1F2G3H4J5K6M7N8P9",
  "inbox_id": "shop-helper@simail.email",
  "thread_id": "thr_01JZX4A1B2C3D4E5F6G7H8J9K0",
  "in_reply_to": "msg_01JZX4A9B8C7D6E5F4G3H2J1K0",
  "to": ["ada@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Re: Where is my order?",
  "text": "Hi Ada, it shipped today.",
  "attachments": [],
  "labels": [],
  "send_at": null,
  "status": "draft",
  "send_id": null,
  "created_at": "2026-10-18T17:04:00Z",
  "updated_at": "2026-10-18T17:04:00Z"
}

status is draft until it is sent, then follows its send: scheduled, pending_approval, sent, blocked, rejected, expired or cancelled. send_id links it to Sends.

List drafts

GET/v0/inboxes/{inbox_id}/drafts

Permission message_read. Paginated; returns { count, limit, next_page_token?, drafts }.

Create a draft

POST/v0/inboxes/{inbox_id}/drafts

Permission draft_write. Body: the send fields (to, cc, bcc, subject, text, html, attachments, labels, send_at), plus in_reply_to (a message_id) to make it a reply. A reply draft takes its recipients from the original message, like a reply. Supports Idempotency-Key.

Get, update or delete a draft

GET/v0/inboxes/{inbox_id}/drafts/{draft_id}

PATCH/v0/inboxes/{inbox_id}/drafts/{draft_id}

DELETE/v0/inboxes/{inbox_id}/drafts/{draft_id}

GET needs message_read; PATCH and DELETE need draft_write. Only drafts in draft status can be changed. Deleting a draft that was already submitted (scheduled or waiting for approval) cancels the send first; if it is already sending or final, the delete returns 409 conflict and the draft is kept.

Upload an attachment

POST/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments

Permission draft_write. Body { "filename", "content_type", "content" } with base64 content (request bodies up to 5 MiB). Returns { "attachment_id", "filename", "size", "content_type" }. A draft can carry at most 32 attachments and about 3.5 MiB of raw attachment data in total. Outbound attachments must be allowed by your send policy.

GET/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}

Permission message_read. Returns a single-use download link, like message attachments.

Send a draft

POST/v0/inboxes/{inbox_id}/drafts/{draft_id}/send

Permission message_send. Idempotency-Key required. Same responses and errors as Send message. Publishes draft.submitted.

Organization-wide drafts

GET /v0/drafts · GET /v0/drafts/{draft_id} · GET /v0/drafts/{draft_id}/attachments/{attachment_id}

Permission message_read, across every inbox in your key’s scope. Pod variants are under /v0/pods/{pod_id}/drafts.

MCP: create_draft, update_draft, get_draft, list_drafts, delete_draft and send_draft (idempotency_key required).