---
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.
  - `from_email` string
  - `from_name` string
  - `to` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string
  - `cc` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string
  - `bcc` EmailAddressInput[]
    - union
      - string
      - EmailAddress
        - `email` string, required
        - `name` string
  - `reply_to` string
  - `subject` string
  - `text_body` string
  - `html_body` string
  - `text` string — Alias for `text_body`, matching the send endpoint.
  - `html` string — Alias for `html_body`, matching the send endpoint.
  - `headers` object
  - `attachments` object[]
  - `labels` string[]
  - `tags` string[]
  - `metadata` object

## Response `201`

The created draft.

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