Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 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

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).

from_namestring

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

group_idstring uuid nullable

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

headersobject

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

html_bodystring

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

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.

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).

inline_cssboolean
metadataobject

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

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.

sandbox_modeboolean
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.

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 and reporting. Stored on the message and propagated to Email Detail Records. Not returned in API 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. Returned only by GET /email_messages/{id}; omitted from create and list responses.

Response

Message queued, scheduled, or sandbox-created.

Example response

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