---
title: "Create a draft"
method: POST
path: "/api/v1/drafts"
tags: ["drafts"]
---

# Create a draft

`POST /api/v1/drafts`

## Request

- Base URL: `https://postfleet.ai`
- URL: `https://postfleet.ai/api/v1/drafts`
- Auth: HTTP bearer

Creates a voluntary draft in status `draft`. Requires `can_send`. The draft is not forced into the approval queue at creation time even on a `require_approval` mailbox — forcing happens at send time. `to` is required unless `reply_to_message_id` is supplied. Note: draft creation has no `client_id` idempotency yet — a retried create can duplicate a draft.

## Request body

- SendRequest
  - `mailbox_id` string, required: Mailbox to send from. A mailbox-bound key must match this.
  - `text` string, required: Plain-text body.
  - `to` string: Single recipient address. Required unless replying; must be exactly one address.
  - `subject` string
  - `reply_to_message_id` string: Reply in-thread to an existing message; resolves `to`/`subject`/thread from the original.
  - `client_id` string: Idempotency key for duplicate protection. Must not start with `draft:` (reserved).
  - `attachments` union[]: Optional files to attach. Each item is exactly one of base64 `content` or an HTTPS `url` (fetched at send time). Filename and content_type are optional. At most 20 files; 6 MB total inline, 30 MB total URL-backed. Bytes are not echoed on draft reads.
    - union
      - object
        - `filename` string: Basename only — no path separators. Derived from the URL path, or `attachment`, when omitted.
        - `content` string, required: File bytes, standard base64.
        - `content_type` string: MIME type. Defaults to application/octet-stream, or the URL response Content-Type.
      - object
        - `filename` string: Basename only — no path separators. Derived from the URL path, or `attachment`, when omitted.
        - `url` string, required: HTTPS URL fetched at send time. Not forwarded to the provider.
        - `content_type` string: MIME type. Defaults to application/octet-stream, or the URL response Content-Type.

## Response `201`

Draft created.

- object
  - `id` string, required
  - `status` 'draft', required

## Other responses

- `400`: Validation error (missing `mailbox_id`/`text`, bad `client_id`, `to` not a single address, missing `to` when not replying).
- `401`: Missing or invalid bearer token, or a key whose scope is not permitted for this endpoint.
- `403`: Key cannot send, or is scoped to a different mailbox (`code:key_scope`).
- `404`: Mailbox not found, or (when replying) the original message was not found / not visible to a mailbox-bound key.

---

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