Sign in
Email Messages

Create or send an email message

Queues, schedules, or sandbox-sends an email message. The legacy /v2/emails POST route is a backward-compatible alias for this operation.

subject is required unless template_id is supplied. When using template_id, do not also provide subject, html_body, or text_body; the template is rendered with template_variables.

Note: template lookup failures (not found, wrong account) return 400, not 404.

post/email_messages

Headers

Idempotency-Keystring

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

Request body

from_namestring

Optional display name for string from; overrides from.name when provided.

group_idstring uuid

Optional unsubscribe group ID. Associates the message with an unsubscribe group for group-scoped suppression handling.

headersobject

Custom email headers. Write-only; not returned in responses.

html_bodystring

HTML email body. Write-only; not returned in responses.

ignore_suppressionboolean

When true, bypasses suppression checks for overridable blocks. Requires the email:override API key scope. Overrides are audited. Non-overridable suppressions (hard bounces, spam complaints, invalid addresses) cannot be bypassed.

inline_cssboolean
metadataobject

Custom metadata. Write-only; not returned in responses.

sandbox_modeboolean
send_atstring date-time

Future ISO 8601 time to schedule sending. Invalid or past timestamps are silently ignored and the email is sent immediately.

subjectstring

Required unless template_id is supplied. When using a template, the template's subject is rendered; if the template has no subject or renders empty, the request returns 400.

tagsstring[]

Tags for categorization. Write-only; not returned in responses.

template_idstring uuid
template_variablesobject

Variables for Liquid template rendering. Non-object values may cause a 422 validation error on message creation, but are silently treated as an empty object for template rendering.

text_bodystring

Plain text email body. Write-only; not returned in responses.

Response

Message queued, scheduled, or sandbox-created.

Changes