Sending Email with the Telnyx API

The Telnyx Email API is a full email platform: transactional and marketing sending with attachments, templates, scheduling, and batch operations — plus open/click/unsubscribe tracking, automatic suppressions, group-scoped unsubscribe management, and a complete event lifecycle from queued to delivered. This guide covers the sending surface in depth. For receiving email, managing inboxes, or tracking events, see the Email API Overview. All requests use the production base URL https://api.telnyx.com/v2 and an Authorization: Bearer YOUR_API_KEY header.

Send a message

Send an email with POST /email_messages. The only required fields are from and to; subject is required unless you’re sending with template_id.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": {
      "email": "sender@example.com",
      "name": "Telnyx Notifications"
    },
    "to": [
      {
        "email": "recipient@example.com",
        "name": "Ada Lovelace"
      }
    ],
    "subject": "Welcome",
    "html_body": "<h1>Welcome, Ada!</h1><p>Thanks for signing up.</p>",
    "text_body": "Welcome, Ada! Thanks for signing up."
  }'

Address fields

Field	Type	Notes
`from`	string \| object	A plain email string or `{email, name}`.
`from_name`	string	Optional display name when `from` is a string; overrides `from.name`.
`to`	array (min 1)	Each item is a string or `{email, name}`.
`cc`	array	Same item shape as `to`.
`bcc`	array	Same item shape as `to`.
`reply_to`	string \| object	Reply-to address. When provided as an object, only the email is stored.

Body, headers, and attachments

Field	Type	Notes
`subject`	string	Required unless `template_id` is supplied.
`html_body`	string	HTML body. Omitted from create and list responses; returned by `GET /email_messages/{id}`.
`text_body`	string	Plain-text body. Omitted from create and list responses; returned by `GET /email_messages/{id}`.
`headers`	object of string keys to string values	Custom headers. Write-only — not returned in responses.
`tags`	array of strings	Tags for categorization. Stored on the message and returned on message responses.
`metadata`	object	Custom metadata. Stored on the message and returned on message responses.
`attachments`	array	See below.

Send an attachment by base64-encoding its content:

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Invoice attached",
    "text_body": "Your invoice is attached.",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "content": "JVBERi0xLjQK..."
      }
    ]
  }'

Request attachments[] fields:

Field	Default	Notes
`filename`	`"attachment"`	Attachment file name.
`content_type`	`application/octet-stream`	MIME type.
`content`	`""`	Base64-encoded file content.
`disposition`	`"attachment"`	Use `inline` for images referenced from the HTML body.
`content_id`	`null`	Content-ID for an inline attachment, referenced as `cid:<content_id>` in the HTML body.

Response attachments[] returns filename, content_type, url, sha256, size_bytes, disposition, and content_id. The base64 content you submitted is never returned — fetch the stored file from url instead.

Templates

Send with a stored template instead of inline bodies. Provide template_id and optional template_variables for Liquid rendering. When you use a template, subject is optional — the template’s subject is rendered; if the template has no subject or renders empty, the request returns 400.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "template_id": "7a7c1a2b-1111-4c72-8c21-2bbf3d40c123",
    "template_variables": {
      "first_name": "Ada"
    }
  }'

Non-object template_variables values may cause a 422 validation error on message creation. Pass an object.

A template can also enforce its own safety controls: strict_variables: true makes a send that is missing a required variable fail with 422 naming the variable (nothing is sent), and autoescape: true HTML-escapes rendered html_body expression output. See Strict variable validation and HTML autoescaping in the Templates guide.

Schedule a send

Set scheduled_at to an ISO 8601 timestamp in the future to schedule the message. The response returns 202 with "status": "scheduled" and a scheduled_at field.

curl

SCHEDULED_AT=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=1)).isoformat(timespec="seconds").replace("+00:00", "Z"))')

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d "{
    \"from\": \"sender@example.com\",
    \"to\": [\"recipient@example.com\"],
    \"subject\": \"Scheduled reminder\",
    \"text_body\": \"This was scheduled.\",
    \"scheduled_at\": \"${SCHEDULED_AT}\"
  }"

Invalid ISO 8601 or non-future scheduled_at values are rejected with HTTP 422; they are never converted into immediate sends.

In batch sends, an invalid or non-future scheduled_at does not fail the whole batch: the invalid item is reported in the 207 per-item errors array while the other items continue.

A scheduled send is not guaranteed to send. Quota and sending-policy checks run when the message fires, not when you submit it. If the account daily limit is exhausted then, the message is marked failed with a daily_limit_exceeded event. If the sender domain’s warm-up ramp rejects it, every recipient is terminalized as failed with reason sender_domain_graduation_rejected; if a fail-closed graduation dependency failure exhausts its retries, the reason is sender_domain_graduation_unavailable. Both graduation outcomes record and publish one recipient-scoped email.failed event per recipient. Because every recipient is terminal, the parent message can roll up to completed through the normal lifecycle even though nothing was sent. No 429 is returned for a scheduled send — there is no HTTP request in flight at fire time. Detect these outcomes via GET /email_events, the per-message events endpoint, or recipient-scoped email.failed webhooks. See Rate Limits & Quotas.

send_at is a deprecated alias for scheduled_at. It is still accepted on requests for backward compatibility, but responses always return scheduled_at. A non-null scheduled_at takes precedence over send_at; if scheduled_at is omitted or null, send_at is used. Use scheduled_at in new integrations.

Reschedule before send

Move a scheduled message to a new future delivery time with PATCH /email_messages/{email_id}/schedule. Only the delivery time changes — the message ID, content, recipients, tags, and metadata remain unchanged.

curl

SCHEDULED_AT=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=1)).isoformat(timespec="seconds").replace("+00:00", "Z"))')

curl -X PATCH https://api.telnyx.com/v2/email_messages/{email_id}/schedule \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d "{ \"scheduled_at\": \"${SCHEDULED_AT}\" }"

Status	Meaning
`200`	Rescheduled. The response matches the single-message GET representation.
`401`	Authentication failed.
`404`	The email message does not exist in your account.
`409`	The message is no longer scheduled, or its scheduled-send worker has already started processing it.
`422`	`scheduled_at` is missing, invalid ISO 8601, or not in the future.

Rescheduling emits no dedicated rescheduled event. The message’s scheduled_at value in the response is the only confirmation of the new delivery time.

Cancel a scheduled message before it sends with DELETE /email_messages/{email_id}/schedule:

curl

curl -X DELETE https://api.telnyx.com/v2/email_messages/{email_id}/schedule \
  -H "Authorization: Bearer ***"

A successful cancel returns 200 with the message in "status": "cancelled". The scheduled_at value persists on the record even after cancellation.

Test delivery outcomes in sandbox mode

Set sandbox_mode: true to validate and accept a message without delivering it: the message is created and events are recorded, but nothing is injected into the MTA or the outbound pipeline. Sandbox messages are non-billable, consume no daily-send-limit quota, and feed no delivery-reputation signals — no impact on your billing, quota, or reputation.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "from": "sender@example.com",
    "to": ["delivered@test.telnyx.com"],
    "subject": "Sandbox test",
    "text_body": "This send is simulated; nothing is delivered.",
    "sandbox_mode": true
  }'

The response is the normal 202 with "status": "sandbox", and the message appears in GET /email_messages and the events endpoints like any other message.

Reserved test recipients

The reserved domain test.telnyx.com hosts eight deterministic test addresses. In sandbox mode, each address produces a fixed, recipient-scoped lifecycle chain — the same outcome every time:

Address	Deterministic event chain	Final event	Persisted recipient status
`delivered@test.telnyx.com`	queued → sending → sent → delivered	`delivered`	`delivered`
`hard-bounce@test.telnyx.com`	queued → sending → sent → bounced (permanent, 5.1.1)	`bounced`	`bounced`
`soft-bounce@test.telnyx.com`	queued → sending → sent → bounced (transient 450, synthetic soft bounce)	`bounced`	`bounced`
`complaint@test.telnyx.com`	queued → sending → sent → complained	`complained`	`sent`
`suppressed@test.telnyx.com`	queued → suppressed	`suppressed`	`suppressed`
`invalid@test.telnyx.com`	queued → sending → failed (invalid recipient)	`failed`	`failed`
`dkim-fail@test.telnyx.com`	queued → sending → failed (DKIM unavailable)	`failed`	`failed`
`rate-limit@test.telnyx.com`	queued → sending → failed (rate limit exceeded)	`failed`	`failed`

For the complaint simulation, complained is the final event, while the recipient’s persisted delivery status remains sent; complaint is an engagement/feedback signal, not a recipient delivery status. Hard-bounce and complaint simulations also exercise the normal automatic-suppression pipeline, so you can test suppression-driven flows deterministically and repeatedly. The constraints are strict:

Sandbox only. These deterministic chains apply only to sends with sandbox_mode: true. Non-sandbox sends to these addresses use the normal delivery path like any other recipient.
Exact domain. Matching is case-insensitive for the local part and domain, but the domain must be exactly test.telnyx.com — subdomains and suffixes do not match.
Only these addresses are simulated. In a mixed sandbox send, other recipients retain ordinary sandbox behavior: accepted, no delivery attempted, no deterministic chain.

Use these addresses to exercise your webhook handling, event polling, and failure-state UI without sending real mail — for example, subscribe to email.sent and email.bounced and send to hard-bounce@test.telnyx.com to verify your bounce path end-to-end.

Sandbox mode is available on batch sends too — set the batch-level sandbox_mode envelope field, which overrides every per-message value. See Batch sending.

Idempotency

Pass an optional Idempotency-Key HTTP header to safely retry a send without creating duplicates. Generate a unique UUID v4 for each logical request, then reuse the same key only when retrying that operation with the same request body. Keys are retained for up to 24 hours, and only successful responses are replayed. Do not include sensitive data in the key.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9326" \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Order confirmation",
    "text_body": "Order #12345 confirmed."
  }'

The first successful request returns its normal status and response body. A retry with the same key and request returns the stored status and body and adds this response header:

Idempotent-Replayed: true

The header is omitted for first-time requests and error responses. Reusing a key with a different request returns 422 with code 10027; sending the same key while the original request is still running returns 409 with code 10036. Empty, duplicate, malformed, or overlong key headers return 400 with code 10015. If Edge cannot provide idempotency protection for a keyed request, it fails closed with 503 and code 10016.

idempotency_key is not a request-body field. Put the key only in the Idempotency-Key HTTP header.

Response

A successful send returns 202 Accepted with the message in data:

{
  "data": {
    "record_type": "email_message",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "status": "queued",
    "from": { "email": "sender@example.com" },
    "to": [{ "email": "recipient@example.com" }],
    "subject": "Welcome",
    "tags": ["welcome"],
    "metadata": { "campaign": "onboarding" },
    "created_at": "2026-07-06T12:00:00.000000Z"
  }
}

Key response fields:

status — the message lifecycle status (see below).
id — the message UUID. Use it with GET /email_messages/{id}, GET /email_messages/{id}/events, and DELETE /email_messages/{id}/schedule.
created_at — when the message was created.
scheduled_at — present when a future send was scheduled.
tags and metadata — the values you supplied, stored on the message and returned on every message response.
recipient_statuses — a map of per-recipient status to count, present once recipient rows exist.
sandbox — present when the message was created in sandbox mode.

Retrieve and filter by tags and metadata

tags and metadata are stored on the message and returned on message responses. List messages having any of a set of tags, or whose metadata contains a set of key/value pairs:

curl

curl --globoff -X GET "https://api.telnyx.com/v2/email_messages?filter[tags]=billing,transactional" \
  -H "Authorization: Bearer ***"

curl

curl --globoff -X GET "https://api.telnyx.com/v2/email_messages?filter[metadata]=campaign=spring,region=us" \
  -H "Authorization: Bearer ***"

filter[tags] — comma-separated tags. Matching is exact and case-sensitive after trimming, and a message matches when it has any of the supplied tags (OR semantics).
filter[metadata] — a JSON object or comma-separated key=value pairs. A message matches when its metadata contains all supplied pairs (containment semantics).

Malformed filters fail closed with 400: empty tag segments, metadata pairs without =, empty keys, and non-object JSON all reject the request.

Message status, recipient status, and event types are three different taxonomies. A message is a request; each recipient has its own delivery outcome; engagement signals such as opens and clicks are events, never message statuses.

Message status

The parent message status is request-lifecycle only — it does not describe delivery.

Status	Meaning
`queued`	Accepted and waiting to be processed.
`scheduled`	Held for a future `scheduled_at` time.
`sending`	Being injected into the delivery pipeline.
`completed`	Every recipient has reached a terminal state (not necessarily success).
`cancelled`	A scheduled message was cancelled before sending.
`sandbox`	Created in sandbox mode; never actually delivered.
`failed`	The message failed before delivery injection, such as when a scheduled send exceeds the daily limit at fire time.

Recipient status

Each recipient carries its own delivery outcome. These are surfaced in recipient_statuses and through the recipients endpoints. The Events API uses a separate event-type taxonomy — several recipient statuses map lossily to a different stored event type (for example, expired, gw_reject, and injection_timeout all produce a failed stored event). For exact recipient status, use recipient_statuses or the recipient endpoints.

Status	Terminal	Meaning
`queued`	No	Accepted, not yet injected.
`sending`	No	Injection in progress.
`sent`	No	Accepted by the delivery gateway.
`deferred`	No	Temporary failure (4xx); will be retried.
`delivered`	Yes	The receiving mail server accepted the message.
`bounced`	Yes	Permanently rejected by the receiving server (5xx or out-of-band bounce).
`failed`	Yes	Terminal system or operator-caused non-delivery.
`expired`	Yes	Retries were abandoned after the maximum queue age.
`gw_reject`	Yes	The delivery gateway refused the recipient before queueing.
`cancelled`	Yes	Cancelled before delivery.
`injection_timeout`	Yes	The injection attempt timed out with an ambiguous result.

Event types

Events record what happened and when. Query them with GET /email_messages/{id}/events or GET /email_events.

Event type	Meaning
`queued`, `scheduled`, `sending`, `sent`, `cancelled`, `sandbox`	Lifecycle progress.
`delivered`, `deferred`, `bounced`, `failed`, `rejected`	Delivery outcomes.
`opened`, `clicked`, `unsubscribed`, `complained`	Engagement and feedback signals.
`daily_limit_exceeded`	The account’s daily send limit blocked the send.

Suppressed recipients

When one or more recipients are suppressed at send time, the 202 response includes a top-level suppressed array describing each suppressed recipient. The message is still created for the non-suppressed recipients (if any).

{
  "data": {
    "record_type": "email_message",
    "id": "...",
    "status": "queued"
  },
  "suppressed": [
    {
      "to": "suppressed@example.com",
      "reason": "hard_bounce",
      "scope": "global",
      "override_allowed": false
    }
  ]
}

If all recipients are suppressed, the request returns 422 with a recipient_suppressed error and the suppressed array (see Errors).

Tracking

Open, click, and unsubscribe tracking are configured through the tracking object on an email domain:

curl

curl -X PATCH https://api.telnyx.com/v2/email_domains/{domain_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "tracking": {
      "open_tracking": true,
      "click_tracking": true,
      "unsubscribe_tracking": true
    }
  }'

Tracking is scoped to the sending profile, not to an individual domain. The domain endpoint is the API surface, but the setting is stored on your account’s default sending profile. Every domain that shares that profile shares one tracking configuration, so updating tracking through one domain changes it for all of them. Registering a domain with tracking in POST /email_domains therefore only works for the first domain on the account — once a profile exists, the request is rejected with a validation error and you must use PATCH /email_domains/{id} instead.

Defaults for a new domain: open_tracking: false, click_tracking: false, unsubscribe_tracking: true. Open and click tracking are opt-in; one-click unsubscribe is on by default because Gmail and Yahoo bulk-sender rules require RFC 8058 unsubscribe support — disable it only if you handle unsubscribes yourself. The tracking endpoints themselves are public (no auth) because email clients and browsers hit them directly.

Open tracking

When open_tracking is enabled, messages with an HTML body get a 1×1 transparent tracking pixel injected before the closing </body> tag (or appended to the HTML when there is no </body>). When the recipient’s email client loads the image, Telnyx records an email.opened event.

Click tracking

When click_tracking is enabled, Telnyx rewrites href links in the HTML body to point through a tracking redirect. When a recipient clicks, Telnyx records an email.clicked event and redirects (HTTP 302) to the original URL. Links already pointing to the tracking service are not double-wrapped.

Unsubscribe tracking

When unsubscribe_tracking is enabled (the default), Telnyx adds List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058) headers to outgoing messages, with a signed, unguessable unsubscribe URL. A recipient can unsubscribe via a link (GET) or one-click (POST, sent automatically by supporting email clients). On unsubscribe, Telnyx records an email.unsubscribed event and creates a suppression for the recipient.

Tracking events

Tracking events — email.opened, email.clicked, and email.unsubscribed — are stored as message events and delivered to configured webhooks. Query them per message:

curl

curl https://api.telnyx.com/v2/email_messages/{id}/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Or list events across the account:

curl

curl https://api.telnyx.com/v2/email_events \
  -H "Authorization: Bearer YOUR_API_KEY"

The email.opened event payload includes a first_open boolean that is true for the first open and false for subsequent opens. The email.clicked payload includes the clicked url, and email.unsubscribed includes the method (link or one_click).

A dedicated deep-dive on email webhooks is coming soon. Until then, event data is available via the endpoints above.

Errors

API errors return structured JSON. See the full Error Codes reference for all codes and troubleshooting. The standard error envelope:

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "subject is required when not using a template"
    }
  ]
}

Common error codes

HTTP	Code	Meaning
400	`10015`	Validation failed — missing or invalid fields.
400	`10015`	Invalid `Idempotency-Key` header — empty, duplicate, malformed, or overlong.
401	`10006`	Authentication failed — check your API key.
403	`10007`	Forbidden — the Email API’s general sending-policy error. Covers an unverified, degraded, or suspended sending domain, a domain with no active DKIM key, a sender that doesn’t match the domain’s sending profile, and trial-account recipient restrictions. Inspect `detail` for the specific reason.
404	`10001`	Not found — the message, domain, or resource doesn’t exist.
409	`10036`	A request with the same idempotency key is still being processed.
413	`10015`	Request body exceeds 8,000,000 bytes.
422	`10015`	Validation error (changeset).
422	`10027`	The idempotency key was already used for a different request.
422	`recipient_suppressed`	All recipients suppressed. Returns a top-level `suppressed` array.
429	`10011`	The account’s daily send limit was exceeded — rejected before message creation, resets at midnight UTC.
429	`domain_graduation_limit_exceeded`	The sender domain’s warm-up ramp daily recipient limit was exceeded — rejected before message creation. The only Email API `429` that carries the `Retry-After` header.
429	`reputation_suspended`	Sending suspended — the sending domain’s reputation band is `poor`.
503	`10016`	Service unavailable — an upstream dependency or Edge idempotency protection is unavailable.

recipient_suppressed (422) uses a non-standard envelope with the suppressed array alongside errors:

{
  "errors": [
    {
      "code": "recipient_suppressed",
      "title": "Recipient Suppressed",
      "detail": "All recipients are suppressed. The email was not sent."
    }
  ],
  "suppressed": [
    {
      "to": "suppressed@example.com",
      "reason": "hard_bounce",
      "scope": "global",
      "override_allowed": false
    }
  ]
}

reputation_suspended (429) uses a string code rather than a numeric Telnyx code:

{
  "errors": [
    {
      "code": "reputation_suspended",
      "title": "Sending Suspended",
      "detail": "Sender domain reputation is too low. Sending has been suspended. Please contact support to resolve deliverability issues."
    }
  ]
}

domain_graduation_limit_exceeded (429) is returned when the sender domain is still in warm-up and the send would exceed the domain’s daily ramp allowance. The Retry-After response header carries the seconds to the domain’s midnight UTC reset — this is the only Email API 429 that sets it. The meta fields are present only when known:

{
  "errors": [
    {
      "code": "domain_graduation_limit_exceeded",
      "title": "Too Many Requests",
      "detail": "Daily send limit of 250 recipients for this sender domain exceeded. The limit resets at midnight UTC.",
      "meta": {
        "retry_after_seconds": 3600,
        "remaining_today": 0
      }
    }
  ]
}

The send is rejected before message creation — no message record, no recipients, no events, no billing. The account daily quota is checked first; the domain ramp applies only to sends that fit the account quota. See Rate Limits & Quotas for the ramp’s ordering, counting, and retry rules, and Error Codes for the complete reference.

Batch sending

Send up to 1,000 messages in a single request with POST /email_messages/batch. Each item in the messages array mirrors the single-send message schema — same fields and validation — except the single-send-only reply and forward threading fields (in_reply_to_message_id, reply_to_all, and forward_of_message_id), which are not accepted on batch items.

curl

curl -X POST https://api.telnyx.com/v2/email_messages/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 20dbec69-bc70-4fed-aec7-2a70af37a8a6" \
  -d '{
    "sandbox_mode": true,
    "messages": [
      {
        "from": "sender@example.com",
        "to": ["delivered@test.telnyx.com"],
        "subject": "Hello 1",
        "text_body": "Message 1"
      },
      {
        "from": "sender@example.com",
        "to": ["hard-bounce@test.telnyx.com"],
        "subject": "Hello 2",
        "text_body": "Message 2"
      }
    ]
  }'

The Idempotency-Key applies to the entire batch request. Reuse it only when retrying the same batch body; do not add per-message idempotency keys inside messages. sandbox_mode on the batch envelope applies to every message in the batch and is the authoritative value: it overwrites each message’s own sandbox_mode before processing, including the false default when the envelope omits the field. A per-message sandbox_mode: true inside a non-sandbox batch is therefore a real send — set the envelope field (not the per-message field) to run batch items in sandbox mode. A sandbox batch gets the same deterministic test-recipient outcomes, consumes no daily-send-limit quota, and is non-billable.

207 — returned after request-wide admission checks pass and item processing runs. When all messages succeed, errors is empty and every item is in data. When one or more items fail, the response contains a data array for successes (which may be empty) and an errors array for failures. Request-wide gates can instead reject the whole batch with 4xx or 5xx before item processing.

The errors array for a batch uses a per-item shape — each entry has index (zero-based position in the request array), code, and message (not detail):

{
  "data": [
    {
      "record_type": "email_message",
      "id": "11111111-1111-1111-1111-111111111111",
      "status": "queued"
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "bad_request",
      "message": "from, to, and subject are required"
    }
  ],
  "meta": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

Batch item error codes: bad_request, unprocessable_entity, not_found, forbidden, service_unavailable, validation_error, recipient_suppressed, and reputation_suspended. unprocessable_entity is returned when an individual message exceeds the size limits — the rest of the batch still processes. For batch rate limits, request-size budgets, retry patterns, and template-based personalization at scale, see the Batch Sending guide.

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

Sending Email with the Telnyx API

Send a message

Address fields

Body, headers, and attachments

Templates

Schedule a send

Reschedule before send

Test delivery outcomes in sandbox mode

Reserved test recipients

Idempotency

Response

Retrieve and filter by tags and metadata

Message status

Recipient status

Event types

Suppressed recipients

Tracking

Open tracking

Click tracking

Unsubscribe tracking

Tracking events

Errors

Common error codes

Batch sending

​Send a message

​Address fields

​Body, headers, and attachments

​Templates

​Schedule a send

​Reschedule before send

​Test delivery outcomes in sandbox mode

​Reserved test recipients

​Idempotency

​Response

​Retrieve and filter by tags and metadata

​Message status

​Recipient status

​Event types

​Suppressed recipients

​Tracking

​Open tracking

​Click tracking

​Unsubscribe tracking

​Tracking events

​Errors

​Common error codes

​Batch sending

Send a message

Address fields

Body, headers, and attachments

Templates

Schedule a send

Reschedule before send

Test delivery outcomes in sandbox mode

Reserved test recipients

Idempotency

Response

Retrieve and filter by tags and metadata

Message status

Recipient status

Event types

Suppressed recipients

Tracking

Open tracking

Click tracking

Unsubscribe tracking

Tracking events

Errors

Common error codes

Batch sending