---
title: "Write a draft (not sent)"
method: POST
path: "/v1/drafts"
tags: ["send"]
---

# Write a draft (not sent)

`POST /v1/drafts`

## Request

- Base URL: `https://botmail.pro`
- URL: `https://botmail.pro/v1/drafts`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bm_session`

Scope: send. Saves an email without sending it and returns
`review_url` (https://botmail.pro/approve/<random token>): a page that
shows the email with Send and Discard buttons and needs no sign-in, so
an agent can hand it to its human. The token is only returned here.
`reply_to_message_id` drafts a reply (recipients and subject default to
the reply's). Same validation as sending (400 invalid_recipient /
no_recipients / empty_body, 422 undeliverable_domain); 429
too_many_drafts above 200 open drafts.

## Request body

- object
  - `mailbox_id` string
  - `to` union: One address string (may be "a@x, b@y") or an array of addresses.
    - string
    - string[]
  - `cc` union: One address string (may be "a@x, b@y") or an array of addresses.
    - string
    - string[]
  - `bcc` union: One address string (may be "a@x, b@y") or an array of addresses.
    - string
    - string[]
  - `subject` string
  - `text` string
  - `html` string
  - `reply_to_message_id` string

## Response `201`

The draft, with review_url.

- Draft
  - `id` string, required: drf_…
  - `mailbox_id` string, required
  - `from` string, required
  - `to` string[], required
  - `cc` string[]
  - `bcc` string[]
  - `subject` string, required
  - `text` string
  - `html` string
  - `reply_to_message_id` string
  - `status` 'draft' | 'sent' | 'discarded', required
  - `sent_message_id` string
  - `review_url` string, uri: Only in the create response.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Invalid request (`bad_request` or a more specific code).
- `401`: Missing or invalid credentials (`unauthorized`, `invalid_token`).
- `422`: Well-formed but rejected; see `code` and `hint`.
- `429`: Too many requests (`rate_limited`, `invite_limit`). Wait `Retry-After` seconds.

---

[API](https://skmtc.dev/botmail/apis/botmail-api.md) · [All operations](https://skmtc.dev/botmail/apis/botmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botmail/apis/botmail-api/revisions/49f736362bf2?raw)