Telnyx Email has two different kinds of errors: request errors returned immediately by the API and delivery errors produced after a message is accepted. Use this guide to tell them apart, read the right fields, and decide whether a retry is safe.
Start with the HTTP response
Send requests return a standard errors array when the API cannot accept the message. Use -i while troubleshooting so you can see the HTTP status as well as the JSON body:
curl -i -X POST "https://api.telnyx.com/v2/email_messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "sender@mail.yourcompany.com",
"to": ["recipient@example.com"],
"subject": "Order update",
"text_body": "Your order has shipped."
}'
Each immediate error contains code, title, and detail, and may include a source pointer. Fix the field or account condition named in detail before retrying.
Common response | What to do |
| Correct the malformed, missing, or conflicting request field. |
| Check the API key, account state, permissions, trial-recipient restrictions, or sender-domain eligibility. |
| Every recipient was suppressed, so no message was created. Inspect the top-level |
| Read the error code before retrying. A daily quota can be retried after reset, but |
Keep the size limits separate
The Email API, its HTTP parser, and Edge idempotency enforce different limits. They do not all return the same status.
Limit | What is measured | Result when exceeded |
1 MB | Decoded |
|
25 MB | Decoded bodies plus decoded attachment bytes. Base64 characters are not the attachment measurement. |
|
150 MB | The complete HTTP request handled by the Email API parser. | The request is rejected before normal send validation. |
8,000,000 bytes | The raw request body only when | Edge returns |
An unkeyed request bypasses the 8,000,000-byte Edge cap, but it is still subject to the 1 MB body, 25 MB total-message, and 150 MB parser limits.
Read delivery errors after acceptance
A 202 Accepted response means Telnyx created the message; it does not guarantee final delivery. Retrieve the message event history with the message ID:
curl "https://api.telnyx.com/v2/email_messages/{message_id}/events" \
-H "Authorization: Bearer YOUR_API_KEY"
Delivery failures use normalized 30xxx codes. Raw SMTP evidence, when available, is preserved separately.
Code | Meaning | Action |
| Hard bounce | Do not retry the same address. Correct it or remove it. |
| Deferred | Temporary SMTP failure. This is the retryable 30xxx outcome. |
| Injection failure | Do not retry automatically. Record the evidence and investigate the injection failure. |
| Suppressed recipient | Defined for normalized delivery records, but the public send-time path filters suppressions before recipient persistence. All-suppressed sends instead return synchronous |
| Queue expiry | Terminal |
| Gateway rejection | The recipient was rejected before it entered the delivery queue. Do not assume it is billable or safe to retry. |
| Internal error | Do not loop automatically. Preserve the message and recipient IDs and contact support if it persists. |
Queue expiry is not the same as a generic failure. The recipient status is terminal expired, while its public webhook is delivered as email.bounced with code 30005.
Use error_evidence as the decision record
Field | Meaning |
| Normalized Telnyx 30xxx outcome. |
| Available delivery detail. It may come from an MTA or operator path, so do not always label it as remote-server text. |
| Enhanced SMTP status when available, such as |
| Raw SMTP numeric status, kept separate from the normalized code. |
| The classifying layer, such as |
| Whether the normalized delivery outcome is safe to treat as temporary. |
What to include in a support request
Include the Telnyx message ID, recipient ID, UTC occurrence time, HTTP status, API error object, and delivery error_evidence. Never include your API key or the message body.