---
title: "Create a draft email"
method: POST
path: "/v1/emails/draft"
---

# Create a draft email

`POST /v1/emails/draft`

Creates a draft in the connected email account that owns the `from` address. Mirrors native email-client behavior: only `from` is required — `to`, `cc`, `bcc`, `subject`, `messageBody`, and `attachments` are all optional. At least one of those optional fields must be populated; sending only `from` returns a 400.

Supports idempotency via the `Idempotency-Key` header.

**[Required scope](/using-the-api/scopes/):** `emails:create`

**[Rate limit category](/using-the-api/rate-limits/):** Write

## Headers

- `Lightfield-Version` '2026-03-01', required

## Request body

- object
  - `from` string, required — Bare email address (no display name). Must match a connected email account owned by the API key user. Compared case-insensitively. Mailbox where the draft is created.
  - `to` string[] — Recipient email addresses (bare, no display names). Up to 500.
  - `cc` string[] — Cc recipients (same shape as `to`).
  - `bcc` string[] — Bcc recipients (same shape as `to`).
  - `subject` string — Email subject.
  - `messageBody` object — Email message body (HTML or plain text).
    - `contentType` 'HTML' | 'TEXT' — Defaults to `HTML`.
    - `content` string, required — Email body content.
  - `attachments` string[] — Optional list of file IDs (uploaded via the Files API) to attach to the draft. Maximum 5 attachments per draft, each ≤ 3MB.

## Response `200`

OK

- EmailDraftResponse
  - `draftedAt` string, required — ISO 8601 timestamp of when the draft was created.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `409` — 409
- `415` — 415
- `422` — 422
- `429` — 429
- `500` — 500
- `501` — 501
- `503` — 503
- `504` — 504

---

[API](https://skmtc.net/lightfld/apis/api-reference.md) · [All operations](https://skmtc.net/lightfld/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightfld/api-reference/versions/93b6c5de5463/schema)