> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Drafts

> Compose a message without sending it, edit it over several calls, then send it through the full pipeline.

A draft is a message that has been written but not sent. Drafts are how an
agent composes in stages ("subject now, recipients once I know who is
responsible") or prepares something for human review before it goes out.

**Drafts never consume quota and never leave the mailbox.** Nothing is billed
and no mail is dispatched until you send the draft.

| Method | Path                   | Purpose                                                     |
| ------ | ---------------------- | ----------------------------------------------------------- |
| POST   | `/v1/drafts`           | Create a draft                                              |
| GET    | `/v1/drafts`           | List drafts (`?status=draft\|sent\|discarded`, `?inboxId=`) |
| GET    | `/v1/drafts/{id}`      | Fetch one draft                                             |
| PATCH  | `/v1/drafts/{id}`      | Edit fields (pass only what changes)                        |
| DELETE | `/v1/drafts/{id}`      | Discard (kept for audit, can never be sent)                 |
| POST   | `/v1/drafts/{id}/send` | Send it                                                     |

### Create

<ParamField body="inboxId" type="string" required>
  The inbox the draft belongs to.
</ParamField>

<ParamField body="to" type="string[]">
  Recipients. Optional — a draft may start with only a subject.
</ParamField>

<ParamField body="cc" type="string[]">
  CC recipients.
</ParamField>

<ParamField body="bcc" type="string[]">
  BCC recipients.
</ParamField>

<ParamField body="subject" type="string">
  Subject line. Max 500 characters.
</ParamField>

<ParamField body="text" type="string">
  Plain-text body.
</ParamField>

<ParamField body="html" type="string">
  HTML body.
</ParamField>

<ParamField body="inReplyTo" type="string">
  Message id this draft answers, so the sent message threads correctly.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  # 1. Start a draft
  curl -X POST https://api.gork.email/v1/drafts \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inboxId": "inb_728af980b4e", "subject": "Re: Invoice 1042"}'

  # 2. Fill it in as you learn more
  curl -X PATCH https://api.gork.email/v1/drafts/drf_1a2b3c4d \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"to": ["billing@acme.com"], "text": "Payment scheduled for Friday."}'

  # 3. Send it
  curl -X POST https://api.gork.email/v1/drafts/drf_1a2b3c4d/send \
    -H "Authorization: Bearer gork_live_YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { GorkClient } from "@gork/sdk"

  const client = new GorkClient({ apiKey: process.env.GORK_API_KEY })

  const draft = await client.drafts.create({ inboxId: "inb_728af980b4e", subject: "Re: Invoice 1042" })

  await client.drafts.update(draft.id, {
    to: ["billing@acme.com"],
    text: "Payment scheduled for Friday.",
  })

  const sent = await client.drafts.send(draft.id)
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "drf_1a2b3c4d",
      "inboxId": "inb_728af980b4e",
      "toAddresses": [],
      "subject": "Re: Invoice 1042",
      "status": "draft",
      "createdAt": "2026-09-11T08:00:00.000Z"
    }
  }
  ```
</ResponseExample>

### Sending a draft

`POST /v1/drafts/{id}/send` runs the **normal send pipeline** — suppression
list, bulk tripwire, spend cap, daily cap, provider dispatch, usage ledger and
webhooks. A draft is not a way around any guardrail.

* Sending a draft twice is safe: the second call returns the message the first
  one produced (the draft is keyed by `draft:<id>`).
* A draft with no recipients is rejected with `draft_incomplete`.
* A discarded draft can never be sent (`draft_discarded`).
* Sent and discarded drafts cannot be edited (`draft_not_editable`).

## From an agent (MCP)

`gork_create_draft`, `gork_list_drafts`, `gork_update_draft`, `gork_send_draft`
and `gork_discard_draft` cover the whole lifecycle, so an agent can prepare a
message, wait for approval, then send it in one call.