​

Telnyx Messaging: Email — Documentation Index

Email documentation within the Messaging section of the Telnyx developer docs (https://developers.telnyx.com). This file: https://developers.telnyx.com/docs/development/llms/messaging-email-llms-txt.md · Root index: https://developers.telnyx.com/llms.txt

​

Getting Started

• Overview: Telnyx Email API — a full email platform with sending, receiving, inboxes, templates, tracking, suppression management, and deliverability tools.
• Send Your First Email: Send your first email with the Telnyx Email API — add a sending domain, verify DNS, and POST to the /email_messages endpoint.

​

Sending Email

• Email API Guide: Complete guide to sending email with the Telnyx Email API — full payload options, HTML and attachments, scheduling, idempotency, tracking, batch sending, and error handling.
• Migrate to Telnyx: Migrate your email sending from any ESP to Telnyx Email — authentication, sending, templates, webhooks, suppressions, and domain setup.
• Rate Limits: Rate limits, sending quotas, request size limits, and destination provider throttling for the Telnyx Email API — batch sending, scheduled sending, and how to request increases.
• Error Codes: Reference for all Telnyx Email API error codes, HTTP status codes, and troubleshooting guidance.

​

Inboxes

• Manage Inboxes: Create and manage email inboxes, read and reply to messages, organize threads with labels, filter senders, and send drafts with the Telnyx Email Inboxes API.

​

Domains & Validation

• Email Domains & DKIM: Register, verify, and manage sending domains with the Telnyx Email API — DNS records (SPF, DKIM, DMARC, MX, ownership), domain health, DKIM signing, status lifecycle, and reputation.
• Email Validation: Validate email addresses before you send — syntax, MX/deliverability signal, disposable domains, role addresses, and typo suggestions, single and batch.

​

Deliverability

• Deliverability & Warm-up: Build and protect your email sender reputation with Telnyx — domain warm-up, authentication, list hygiene, bounce handling, and complaint monitoring.
• Deliverability Best Practices: Understand email deliverability — how receiving providers evaluate your mail, why messages land in spam, and how to interpret Telnyx delivery error codes when things go wrong.

​

Templates & Suppression

• Templates: Create, manage, and render email templates with the Telnyx Email API — Liquid variables, server-side render/preview without sending, and sending with a template.
• Suppressions & Unsubscribes: Manage the Telnyx Email suppression list — reason taxonomy, account vs group scope, CSV import from SendGrid/Mailgun/SES, send-time override behavior, unsubscribe groups, and RFC 8058 one-click unsub…
• Unsubscribe Groups: Group-based unsubscribe management for the Telnyx Email API — let recipients opt out of specific email categories without unsubscribing from everything.

​

Events & Webhooks

• Webhooks & Events: Track every email event with Telnyx — subscribe via webhooks or poll the Events API. Complete event-type reference, webhook CRUD, Ed25519 signature verification, and polling patterns.
• Event Lifecycle: Understand the full lifecycle of an email message — from send to delivery to bounce — and how each stage maps to Telnyx webhook events, the Events API, and the Email Detail Record (EDR).

​

API Reference (Email)

​

Email Messages

• Delete email messages by address: Permanently deletes every email in the authenticated account sent from or to the
• List email messages: Lists messages sorted newest first by created_at desc, id desc. No filters other than
• Create or send an email message: Queues, schedules, or sandbox-sends an email message. The legacy /v2/emails POST route
• Create a batch of email messages: Creates up to 50 email messages in a single request.
• List events for an email message: Lists events for a single message sorted oldest first by occurred_at asc, id asc.
• Cancel a scheduled email message: Cancels a scheduled email and returns it with status cancelled. The legacy /v2/emails/{id}/schedule DELETE route is an alias.
• Delete an email message: Permanently deletes an account-scoped email message, its events, its durable
• Get an email message: The legacy /v2/emails/{id} GET route is a backward-compatible alias for this operation.
• List recipients for an email message: Lists per-recipient delivery states for a single message with cursor pagination.
• Get a single recipient’s delivery state: Returns the current delivery state of a single recipient, including status,

​

Email Inboxes

• List email inboxes: Lists the account’s non-deleted inboxes newest first using stable cursor pagination.
• Create an email inbox: Creates an inbox on an inbound-enabled domain. When domain_id is omitted, Telnyx
• Delete an email inbox: Soft-deletes an account-scoped inbox. Its address remains reserved and the inbox is no longer returned by list or get operations.
• Get an email inbox: Returns an account-scoped, non-deleted inbox. Missing and foreign inboxes are indistinguishable.
• Remove sender filter entries from an inbox: Removes entries from either the allowlist or blocklist. The operation is
• List sender filters for an inbox: Returns the inbox’s sender allowlist and blocklist. Entries are normalized
• Add sender filter entries to an inbox: Adds entries to either the allowlist or blocklist. The operation is an
• Replace sender filters for an inbox: Replaces both sender filter lists atomically. Omitting either list clears
• List and search messages in an inbox: Lists inbound messages newest first. All access is scoped to the authenticated
• Update an inbox message: Updates the explicit read state of an account-scoped inbound message. Set read_at
• Forward an inbox message: Sends from the inbox address through the standard email send pipeline to caller-supplied
• Reply to an inbox message: Sends from the inbox address through the standard email send pipeline. The recipient is
• Reply all to an inbox message: Sends from the inbox address through the standard email send pipeline. The To list starts
• Remove labels from an inbox message: Removes one or more labels from a message. Idempotent — removing a
• Add labels to an inbox message: Adds one or more mutable labels to a message. Labels carry agent
• List threads in an inbox: Lists thread summaries newest first using stable cursor pagination.
• Get a thread and a page of its messages: Returns a bounded page of inbound and outbound thread messages interleaved in chronological order using stable cursor pagination.
• Remove labels from an inbox thread: Removes one or more labels from a thread. Idempotent — removing a label
• Add labels to an inbox thread: Adds one or more mutable labels to a thread, letting an agent mark a

​

Email Drafts

• List drafts in an inbox: Lists drafts newest first using stable cursor pagination. All access is scoped
• Create a draft: Creates an unsent draft in the inbox. Every field is optional — a draft is a
• Delete a draft: Permanently deletes an unsent draft. Drafts that are being sent or have been sent
• Retrieve a draft: Returns a single draft. Drafts that have been sent remain retrievable, so the
• Update a draft (alias): Identical to PUT; both apply a partial update to the supplied fields.
• Update a draft: Updates the supplied fields on a draft. account_id and inbox_id are
• Send a draft: Sends the draft through the standard send pipeline — the same domain resolution,
• Create a reply draft: Creates an unsent reply draft for an inbound message. Unlike the

​

Email Threads

• List threads across every inbox in the account: Lists thread summaries for the whole account, newest first, using stable
• Get an account-wide thread and a page of its messages: Returns a thread and a bounded page of its inbound and outbound messages,

​

Email Domains

• List email domains: Shared (type: shared) Telnyx-managed domains are included/readable for every account, in addition to the account’s own custom domains.
• Create an email domain: Registers a domain for email sending and optional inbound delivery. The response includes the domain configuration and current verification state.
• Delete an email domain: Deletes an email domain configuration. Verified domains require force=true, and shared domains are read-only for non-owner accounts.
• Retrieve an email domain: Shared (type: shared) Telnyx-managed domains are included/readable for every account, in addition to the account’s own custom domains.
• Update an email domain: Updates mutable settings for an existing email domain, including inbound delivery and tracking configuration. Shared domains are read-only for non-owner accoun…
• Get domain health summary: Returns a summary of domain health including verification status and usability.

​

Email Domain DNS Records

• List DNS records for an email domain: Returns the DNS records Telnyx generated for domain ownership and DKIM verification, plus MX records when inbound delivery is enabled.
• Verify DNS records for an email domain: Checks the published DNS records against the records required for the email domain and returns the latest verification results.

​

Email Webhooks

• List webhooks for an email domain: Returns a paginated list of webhook subscriptions scoped to the email domain. Results can be sorted by creation time.
• Create a webhook for an email domain: Creates a webhook endpoint subscribed to a specific allowlist of event types. Both email.* events (published by email-api) and email_domain.* events (publi…
• Delete a webhook: Deletes the webhook subscription identified by ID within the specified email domain and returns the deleted subscription.
• Retrieve a webhook: Returns the webhook subscription identified by ID within the specified email domain.
• Update a webhook: Update a webhook’s URL and/or event subscription. A webhook is bound to its domain — domain_id is not mutable.

​

Email Validations

• Validate a single email address: Validates a single email address and returns deliverability checks.
• Create a batch email validation job: Creates an asynchronous batch validation job for up to 1,000 email addresses.
• Get a batch email validation job: Retrieves the current status and, once completed, validation results for a batch job.

​

Email Templates

• List email templates: Lists templates sorted newest first by created_at desc, id desc.
• Create an email template: Creates a Liquid email template. Variables are auto-extracted when omitted.
• Delete an email template: Deletes the account-owned template. The operation returns 204 with no body and prevents future sends or renders from using the deleted template ID.
• Get an email template: Returns the account-owned template identified by ID, including its Liquid subject and bodies, declared variables, and timestamps.
• Update an email template: Updates one or more template fields.
• Replace an email template: Replaces template fields. Behaves identically to PATCH; provided for compatibility with Phoenix resource routes.
• Render an email template: Renders a template using the provided Liquid variables. Missing template_variables defaults to {}.

​

Email Suppressions

• List suppressions: Account-scoped list. Two mutually exclusive pagination modes:
• Create a manual suppression: Creates a suppression with reason: manual_block and source: manual.
• Export suppressions as CSV: Streams the account’s suppressions as a chunked CSV (server-side
• Soft-delete a suppression: Soft-deletes (status → removed; tombstone retained). A removed
• Retrieve a suppression: Returns the account-owned suppression identified by ID. Cross-account lookups and malformed IDs return 404 without exposing another account’s data.
• List audit events for a suppression: Offset pagination only (page[number] default 1, page[size]

​

Email Suppression Imports

• Create an async CSV import job: Accepts multipart/form-data with a file field (the CSV) and an
• Poll an import job: Account-scoped fetch (cross-account → 404; malformed UUID → 404).

​

Email Unsubscribe Groups

• List unsubscribe groups: Offset pagination only (page[number] default 1, page[size]
• Create an unsubscribe group: Creates an account-owned unsubscribe group for associating email categories with separate recipient suppression lists.
• Delete an unsubscribe group: If the group has 0 active suppressions, hard-deletes the row. With
• Retrieve an unsubscribe group: Returns the account-owned unsubscribe group identified by ID.
• Update an unsubscribe group: Partial update (only name / description). PUT is not routed.
• List suppressions in a group: Account + group scoped. Offset pagination only (page[number]
• Add a group suppression: Creates a suppression with reason: unsubscribe, source: manual,
• Remove a group suppression: Soft-deletes all active blocks for (account, group, normalized

​

Email Events

• List account email events: Lists account-level email events sorted oldest first by occurred_at asc, id asc.
• Get email event statistics: Returns counts and rates for email events over a time range. The default start time is 30 days ago.