Create a draft email

POST/v1/emails/draft

Creates a draft in the connected email account that owns the from address (its primary address or one of its verified aliases). 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: emails:create

Rate limit category: Write

Body ParametersJSONExpand Collapse

from: string

Bare email address (no display name). The primary address or a verified alias of a connected email account owned by the API key user. Compared case-insensitively. Mailbox where the draft is created.

attachments: optional array of string

Optional list of file IDs (uploaded via the Files API) to attach to the draft. Maximum 5 attachments per draft. Gmail: up to 20 MiB combined raw attachment size. Outlook: up to 3 MiB per attachment. Uploads with purpose email_attachment accept up to 20 MiB per file; sender-specific limits apply when sending or creating a draft.

bcc: optional array of string

Bcc recipients (same shape as to).

cc: optional array of string

Cc recipients (same shape as to).

messageBody: optional object { content, contentType }

Email message body (HTML or plain text).

content: string

Email body content.

contentType: optional "HTML" or "TEXT"

Defaults to HTML.

One of the following:

"HTML"

"TEXT"

subject: optional string

Email subject.

to: optional array of string

Recipient email addresses (bare, no display names). Up to 500.

ReturnsExpand Collapse

EmailDraftResponse object { draftedAt }

draftedAt: string

ISO 8601 timestamp of when the draft was created.

Create a draft email

curl https://api.lightfield.app/v1/emails/draft \
    -H 'Content-Type: application/json' \
    -H 'Lightfield-Version: 2026-03-01' \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
          "from": "sales@acme.com"
        }'

{
  "draftedAt": "draftedAt"
}

Returns Examples

{
  "draftedAt": "draftedAt"
}