Email API: Better Testing, Message Retrieval, and Event Visibility

The Telnyx Email API now makes it easier to test email workflows, retrieve messages, and understand what happens throughout the delivery lifecycle. New sandbox outcomes, message filtering, event names, and webhook coverage give developers more visibility without affecting production sends.

What's new

• Deterministic sandbox outcomes: Set sandbox_mode to true, then use a reserved @test.telnyx.com recipient to simulate delivered, hard-bounce, soft-bounce, complaint, suppressed, invalid-recipient, DKIM-failure, or rate-limit outcomes. The soft-bounce scenario records a terminal bounced outcome with a synthetic 450 response; it does not emit email.deferred.

The exact reserved recipients are:

1. [email protected]
2. [email protected]
3. [email protected]
4. [email protected]
5. [email protected]
6. [email protected]
7. [email protected]
8. [email protected]

• No delivery, billing, or reputation impact: Sandbox messages are not injected into the outbound delivery path, are non-billable, and are excluded from production statistics and sender-reputation calculations. Simulated hard-bounce and complaint outcomes can still create suppressions for the reserved test addresses.
• Richer message retrieval: Message responses now include tags and metadata. Message-list requests can filter using filter[tags] and filter[metadata].
• More precise event coverage: Event polling now includes the additive canonical_event_type field, distinguishing gateway rejection as email.gw_reject, injection timeout as email.injection_timeout, and queue expiration as email.expired without breaking existing integrations.
• More webhook events: Cancellation, daily-limit, and system-failure events can now be delivered through configured webhooks.

Why it matters

Developers can test both successful and failure paths without generating real email traffic, making it easier to validate application behavior before going to production.

Tags and metadata also make message retrieval more useful, while expanded event coverage provides clearer signals about why an email was rejected, delayed, expired, or otherwise failed.

Additional webhook coverage means applications can react to more Email API lifecycle events as they happen.

Getting started

Prerequisites

• A Telnyx account
• A Telnyx API key
• For webhooks, a configured HTTPS webhook endpoint

Set sandbox_mode to true in the send request and choose one of the reserved @test.telnyx.com recipients listed above. For webhook monitoring, subscribe to email.cancelled, email.daily_limit_exceeded, and/or the existing email.failed event as needed.

Use the reserved @test.telnyx.com recipients to trigger deterministic test outcomes. For production monitoring, configure Email API webhooks for the events your application needs to receive.

Learn more in the Email Webhooks and Events documentation and the Email sending documentation.