# Drafts

Source: https://docs.simail.ai/api/drafts/

> Create, edit, list, delete and send drafts; upload outbound attachments to a draft; organization-wide draft listings.

A draft is a message your agent prepares before sending. Sending a draft goes through the same
checks as [Send message](/api/send-message/).

```json
{
  "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](/api/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](/api/send-message/#body) (`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](/api/messages/#get-an-attachment).

## 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](/api/send-message/#responses). 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`](/api/pods/).

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