Skip to main content
Drafts let an agent compose a message and save it without sending. A team member can then review and send it directly from the dashboard. This is especially useful for supervised workflows where the agent handles triage and drafting, but a human approves anything that touches billing, account access, or sensitive topics. Saved drafts retain their uploaded file attachments; unused uploads that are not attached to any draft expire automatically after 24 hours.

List drafts

Returns cursor-paginated saved drafts for the specified inbox. GET /api/v1/inboxes/:id/drafts Requires: email:read

Query parameters

integer
Number of drafts to return. Range: 1–100. Defaults to 25. Large drafts can reduce the number returned per page.
string
Opaque pagination cursor returned as next_cursor in the previous response.
List saved drafts

Create a draft

Saves a draft without sending it. Supply id to replace an existing draft, or omit it to create one. Attach existing upload IDs for file attachments. Drafts are standalone messages and do not retain a link to an original conversation. Recipients, subject, and body can be empty while drafting. Replacing a draft resets omitted fields, so send all fields you want to retain. POST /api/v1/inboxes/:id/drafts Requires: email:send
Save a draft message

Request parameters

string
Existing draft ID to replace. Omit to create a new draft.
string[]
Recipient addresses for the draft. May be empty until sending. Up to 50 recipients across to, cc, and bcc. Accepts plain addresses or RFC 5322 "Name <addr>" format.
string
Subject line of the draft message.
string
Optional plain-text draft body. You may save an empty draft and add content later.
string
HTML draft body displayed in email clients that support it.
string[]
IDs of previously uploaded files to attach to this draft. Upload files first via POST /api/v1/inboxes/:id/uploads. Maximum 10 attachments and 10 MB total.
string
With id: the draft’s updated_at as you last read it. If someone saved the draft since, the save is refused with 409 (details.reason draft_changed) and details.draft holds the current version, so two editors never overwrite each other silently. Omit it to replace the draft whatever its version.
Sending a saved draft from the dashboard or the send endpoint starts a new conversation, even if the subject begins with Re:. To preserve reply headers after a human reviews the text, open the original message and use Reply, or call POST /api/v1/messages/:id/reply with the approved text. That separate reply does not remove the saved draft; delete it when it is no longer needed.

Delete a draft

Permanently removes a saved draft. Attached files are released and may expire if not referenced elsewhere. DELETE /api/v1/drafts/:id Requires: email:send
Delete a draft

Sending a draft

To promote a draft to a sent message, pass its draft_id in the body of the send endpoint. The draft is removed atomically when the message is queued, even if the send is deduplicated by an idempotency_key.
Send a saved draft
Sending requires the email:send scope. On the Free Sandbox, sends are limited to verified recipients (25 per month, 5 per day). A paid plan is required for production support workflows.

Attachment lifecycle

Uploads (unsaved)

Files uploaded via POST /api/v1/inboxes/:id/uploads but not yet attached to a draft or message expire after 24 hours.

Draft attachments

Files referenced in a saved draft are retained as long as the draft exists. Deleting the draft releases the files.