---
title: "Create a draft"
method: POST
path: "/email_inboxes/{inbox_id}/drafts"
tags: ["Email Drafts"]
---

# Create a draft

`POST /email_inboxes/{inbox_id}/drafts`

Creates an unsent draft in the inbox. Every field is optional — a draft is a
work-in-progress and may be saved incomplete. Send-time requirements (sender,
subject, at least one recipient) are enforced when the draft is sent, not when
it is created.

Drafts are unbillable and emit no Email Detail Records until they are sent.

## Path parameters

- `inbox_id` string, uuid, required

## Request body

- EmailDraftRequest — All fields are optional — a draft may be saved incomplete. `account_id`, `inbox_id`, `status`, `sent_at`, `sent_message_id`, `reply_to_message_id` and `thread_id` are server-owned and ignored if supplied.
  - `attachments` object[]
  - `bcc` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string
  - `cc` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string
  - `from_email` string
  - `from_name` string
  - `headers` object
  - `html` string — Alias for `html_body`, matching the send endpoint.
  - `html_body` string
  - `labels` string[]
  - `metadata` object
  - `reply_to` string
  - `subject` string
  - `tags` string[]
  - `text` string — Alias for `text_body`, matching the send endpoint.
  - `text_body` string
  - `to` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string

## Response `201`

The created draft.

- EmailDraftResponse
  - `data` EmailDraft, required — An unsent, mutable draft message belonging to an inbox.
    - `attachments` object[]
    - `bcc` EmailAddress[]
      - `email` string, required
      - `name` string
    - `cc` EmailAddress[]
      - `email` string, required
      - `name` string
    - `created_at` string, date-time
    - `from` string, nullable — Sender address. Defaults to the inbox address at send time when null.
    - `from_name` string, nullable
    - `headers` object — Custom headers. Reply drafts carry `In-Reply-To` and `References`.
    - `html_body` string, nullable
    - `id` string, uuid, required
    - `inbox_id` string, uuid, required
    - `labels` string[] — Mutable mailbox-state labels. Not propagated to Email Detail Records.
    - `metadata` object — Arbitrary customer-defined metadata.
    - `record_type` 'email_draft', required
    - `reply_to` string, nullable
    - `reply_to_message_id` string, uuid, nullable — Inbound message this draft replies to. Server-owned; set only on reply drafts.
    - `sent_at` string, date-time, nullable
    - `sent_message_id` string, uuid, nullable — The email message created when this draft was sent.
    - `status` 'draft' | 'sending' | 'sent', required — `draft` until the draft is sent. A sent draft is retained for audit and becomes immutable.
    - `subject` string, nullable
    - `tags` string[] — Transport/reporting attribution tags, propagated to Email Detail Records at send time.
    - `text_body` string, nullable
    - `thread_id` string, uuid, nullable — Conversation thread inherited from the parent message.
    - `to` EmailAddress[]
      - `email` string, required
      - `name` string
    - `updated_at` string, date-time

## Other responses

- `401` — Not authorized (10006).
- `404` — Resource not found (10001).
- `422` — Validation Failed (10015) or changeset validation error.
- `503` — Drafts or the email domain service are temporarily unavailable (10016).

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/1571b0380bd7/schema)