Sign in

v55

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-051,2852,0364.4 MB
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.

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.

html_bodystring

HTML email body. Returned only by GET /email_messages/{id}; omitted from create and list responses.

text_bodystring

Plain text email body. Returned only by GET /email_messages/{id}; omitted from create and list responses.

headersobject

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

tagsstring[]

Tags for categorization and reporting. Stored on the message and propagated to Email Detail Records. Not returned in API responses.

group_idstring uuid nullable

Optional unsubscribe-group UUID used for group-scoped suppression checks and unsubscribe handling.

ignore_suppressionboolean

When true, allows delivery to recipients whose suppressions explicitly permit an override. Hard bounces, spam complaints, and invalid-address suppressions cannot be overridden. Requires the email:override API scope.

metadataobject

Custom metadata. 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.

scheduled_atstring date-time nullable

Future ISO 8601 time to schedule sending. Invalid or past timestamps are silently ignored and the email is sent immediately. The legacy alias send_at is still accepted for backward compatibility; when both are provided, scheduled_at wins.

send_atstring date-time

Deprecated alias for scheduled_at.

inline_cssboolean
sandbox_modeboolean
in_reply_to_message_idstring uuid nullable

Telnyx message UUID of the message this send replies to. When provided, the API sets RFC 5322 In-Reply-To and References headers on the outbound MIME so the recipient's mailbox (Gmail/Outlook) threads it correctly. The parent is looked up under the caller's account scope; a UUID belonging to another account yields a non-enumerating 404.

Wire-only (Phase 1): the API sets the headers and does NOT resolve or mutate thread_id on the server side. Messages sent without this parameter are standalone (no threading headers injected).

Cannot be combined with forward_of_message_id (422).

reply_to_allboolean nullable

Indicates a reply-all intent. In Phase 1 (wire-only) this does not change the threading headers — recipient selection is customer- controlled (to/cc), and a thread is not defined by its audience. When the referenced message has no thread context, reply-all degrades to a plain reply (parent ID only in References). The resolution engine (separate work) will expand the ancestor chain at a later phase with no API change.

Only meaningful alongside in_reply_to_message_id.

forward_of_message_idstring uuid nullable

Telnyx message UUID of the message this send forwards. Forwarded messages start a NEW thread per RFC 5322 — NO In-Reply-To or References headers are set on the outbound MIME. The id is recorded in the message's metadata for EDR provenance only.

The id is validated as a UUID but is NOT looked up against the message store — existence is the caller's responsibility (the forward is pure metadata; it does not affect delivery). Cannot be combined with in_reply_to_message_id (422).

Response

Message queued, scheduled, or sandbox-created.

Example response

{
  "data": {
    "recipient_statuses": {
      "delivered": 998,
      "bounced": 2
    }
  }
}