Email Webhooks & Events

Every email you send through Telnyx emits events as it moves through the delivery lifecycle — from queued to sent to delivered (or bounced/failed), plus engagement signals like opened and clicked. Your email domains also emit lifecycle webhooks (email_domain.verified, email_domain.suspended, …). This guide covers webhooks, account event polling, and per-message event history. Polling is a first-class option for stored outbound message events: if you don’t have a publicly reachable HTTPS endpoint — common for agents, batch jobs, and on-prem services — you can query GET /email_events with no webhook infrastructure. Polling and webhooks overlap, but their subscription/filter coverage and payload details differ — see Event schemas by surface.

Prerequisites

A Telnyx account with an email domain configured and verified
Your API key
For webhooks: a publicly accessible HTTPS endpoint (or ngrok for local development) and your public key for signature verification

Event model

An email message moves through a series of states. Each transition emits an event carrying the event type, a timestamp, the email message ID, and an optional payload with delivery/engagement details.

Lifecycle of a message

Outbound emails typically progress:

email.scheduled → email.queued → email.sent → email.delivered
                                                  ↘ email.deferred (temporary) → email.delivered
                                                  ↘ email.bounced (terminal non-delivery)
                                                  ↘ email.failed
              ↘ email.sandbox   (sandbox mode only — no delivery attempted)

email.bounced is not limited to a permanent remote rejection. Four distinct MTA outcomes — an ordinary bounce, a queue expiration, an administrative bounce, and an asynchronous out-of-band (OOB) bounce — all publish the same email.bounced webhook. The webhook event type alone does not tell you which one happened. Read payload.error_evidence.code (the 30xxx normalized error code) to distinguish them. The recipient’s authoritative status on the recipient row may differ from the webhook’s status field, which carries the event slug.

The per-recipient status recorded on the recipient row can diverge from the webhook event type. Expiration resolves the recipient to expired, while an administrative bounce resolves it to failed — both still publish email.bounced:

MTA outcome	Webhook event type	Recipient `status`	`error_evidence.code`
Ordinary bounce	`email.bounced`	`bounced`	`30001` (or `30002` on a 4xx)
Queue expiration	`email.bounced`	`expired`	`30005`
Administrative bounce	`email.bounced`	`failed`	`30003` (or `30099` without SMTP status)
Out-of-band (OOB) bounce	`email.bounced`	`bounced`	`30001`

Event names and compatibility

Outbound event envelopes carry two names:

event_type preserves the legacy email.-prefixed name. Webhook subscriptions match this field.
canonical_event_type is additive and identifies the precise outcome, also prefixed with email..
The per-message events endpoint also retains deprecated type, whose value remains the bare stored name. Existing rows retain their stored names; canonical rendering of old rows uses recorded evidence and never guesses a sharper outcome for a legacy failed row.

Outcome	Legacy `event_type`	`canonical_event_type`
Gateway rejection	`email.failed`	`email.gw_reject`
Ambiguous injection timeout	`email.injection_timeout`	`email.injection_timeout`
MTA queue expiration	`email.bounced`	`email.expired`
Hard bounce	`email.bounced`	`email.bounced`
System failure	`email.failed`	`email.failed`

Subscribe to email.bounced to receive expirations and inspect canonical_event_type for email.expired. Neither email.expired nor email.gw_reject is a subscription value. email.injection_timeout is emitted by the email API but is absent from the current domains subscription allowlist; use polling to observe that outcome. Administrative bounce webhooks retain email.bounced with canonical email.failed; polling renders the legacy name from the stored row (email.failed for new recipient-scoped admin failures). After delivery, engagement events fire as recipients interact:

email.delivered → email.opened → email.clicked
                                ↘ email.complained
                                ↘ email.unsubscribed

Inbound emails (messages received at a domain with inbound enabled) emit a single email.received event. Separately, your email domains emit lifecycle events — email_domain.created when a domain is registered, email_domain.verified when its DNS records validate, and email_domain.degraded / email_domain.suspended / email_domain.deleted as its health changes.

Webhook event-type reference

Email webhook subscriptions accept 22 event types: 15 outbound/tracking email.* types, email.received from the inbound pipeline, and 6 email_domain.* lifecycle types. 21 are published; only email.sending is accepted but intentionally not published. The table below lists the published subscription values.

email.sending is accepted by the subscription allowlist but never published as a webhook. The service records a stored sending event when a message is handed to the outbound MTA, but explicitly suppresses its webhook publication (skip_webhook: true). You can subscribe to it, but you will never receive an email.sending callback. The sending event is returned by the Events API — see Consume via polling. Only 21 of the 22 allowed event types are actually delivered as webhooks.

Message lifecycle (`email.*`)

Event type	Trigger	Payload highlights
`email.scheduled`	A message with a future `scheduled_at` has been accepted and queued for later sending.	Webhook publication fans out per recipient and carries `send_at`. Account polling retains one message-scoped scheduled row instead of mirroring that fan-out.
`email.queued`	The message has entered the outbound queue.	Recipient-scoped snapshot: `id`, `recipient_id`, `status`, `occurred_at`, `from`, the single recipient field, and `subject`.
`email.sandbox`	A message was accepted in sandbox mode — no delivery is attempted.	Recipient-scoped snapshot with `status: "sandbox"`.
`email.sent`	The recipient was accepted by the Telnyx outbound MTA for delivery. Remote acceptance is reported by `email.delivered`.	Recipient-scoped snapshot.
`email.delivered`	The receiver accepted the message for this recipient (SMTP success).	Recipient-scoped snapshot with `status: "delivered"`.
`email.deferred`	Delivery temporarily failed; the MTA will retry.	Recipient-scoped snapshot with `status: "deferred"`, plus `error_evidence` and `errors[]`.
`email.bounced`	Terminal non-delivery for this recipient — an ordinary bounce, queue expiration, administrative bounce, or OOB bounce.	Recipient-scoped snapshot with `status: "bounced"` (always the event slug, not the recipient status), plus `error_evidence` and `errors[]`. Use `error_evidence.code` to distinguish bounce subtypes.
`email.failed`	The message could not be sent for this recipient (sender-side failure).	Recipient-scoped snapshot with `status: "failed"`, plus `error_evidence` and `errors[]`.
`email.cancelled`	A queued or scheduled message was cancelled. Published after commit when configured.	Recipient-scoped cancellation events with IDs matching account polling.
`email.daily_limit_exceeded`	A scheduled send exceeds the daily limit at fire time. Published after commit when configured.	Recipient-scoped payload with the configured `limit`.
`email.received`	An inbound message arrived at one of your enabled inbound domains.	Inbound sender, recipients, subject, and stored-content references.

Engagement & tracking (`email.*`)

Event type	Trigger	Payload highlights
`email.opened`	A recipient opened the message (tracking pixel fired).	Recipient, first-open flag, IP address, user-agent.
`email.clicked`	A recipient clicked a tracked link in the message.	Recipient, link URL, user-agent.
`email.complained`	Telnyx received an individual spam feedback report from a participating mailbox provider.	Recipient.
`email.unsubscribed`	The recipient unsubscribed via a tracked unsubscribe link.	Recipient, IP address, user-agent, unsubscribe method.

Domain lifecycle (`email_domain.*`)

Event type	Trigger	Payload highlights
`email_domain.created`	A new email domain was registered to your account.	Domain resource snapshot (`id`, `domain`, `status`, DNS and configuration fields).
`email_domain.verified`	The domain’s DNS records passed verification and it’s ready for sending.	Domain resource snapshot.
`email_domain.degraded`	A previously verified domain failed a later DNS drift check.	Domain resource snapshot.
`email_domain.suspended`	The domain was suspended (reputation or policy).	Domain resource snapshot.
`email_domain.deleted`	The domain was deleted.	Domain resource snapshot.
`email_domain.dkim_rotated`	A custom domain DKIM key was rotated.	Updated domain resource snapshot with replacement DKIM DNS values.

The six email_domain.* events come from the domains service. GET /email_events returns stored outbound message events, including cancellation, daily-limit, and system failures; it does not backfill domain lifecycle events or email.received. Cancellation, daily-limit, and system-failure webhook publication runs after the event transaction commits, when the domain has a matching subscription. Event IDs match across webhook delivery and account polling for stored recipient events and for the queued, sending, sandbox, cancelled, and daily_limit_exceeded message-event fan-outs. Scheduled is the exception: polling returns one message-scoped stored row, while webhooks derive one event ID per recipient, so scheduled webhook IDs do not appear in polling.

Consume via webhooks

Webhooks push events to your HTTPS endpoint in real time. Email webhooks are scoped to a domain: you create a subscription on a specific email domain, and it fires only for the event types you allowlist on that subscription.

Webhook payload envelope

Delivery webhooks are recipient-scoped, not message-scoped. One recipient produces one webhook event carrying one status and one address. The payload never contains arrays of to/cc/bcc. A message sent to three recipients produces three separate email.delivered callbacks, each with its own recipient_id and its own outcome. This differs from the Events API, which returns stored events with mixed cardinality (message-scoped admission events plus per-recipient delivery transitions) — see Event schemas by surface.In rare cases where a callback carries no durable recipient ID (for example, an ownership mismatch or a pre-recipient-ID legacy message), the webhook falls back to a message-scoped payload without recipient_id. Treat recipient_id as present in the normal case but do not crash on its absence.

Every webhook delivery is an HTTP POST with a JSON body in this shape:

{
  "data": {
    "event_type": "email.delivered",
    "canonical_event_type": "email.delivered",
    "id": "f3a2c1d0-1234-4abc-9def-67890abcdef0",
    "occurred_at": "2026-07-06T18:24:00.000Z",
    "payload": {
      "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
      "recipient_id": "7c1e9a44-2f60-4d1b-9a0e-3c7b5e8d1f22",
      "status": "delivered",
      "occurred_at": "2026-07-06T18:24:00.000Z",
      "from": { "email": "sender@example.com", "name": "Telnyx" },
      "to": { "email": "recipient@example.com", "name": null, "kind": "to" },
      "subject": "Welcome"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1
  }
}

Field	Description
`data.event_type`	One of the 21 published subscription types above (`email.sending` is accepted but never delivered).
`data.canonical_event_type`	Additive canonical outcome name on outbound message events; subscriptions still match `data.event_type`.
`data.id`	Unique identifier for this event delivery. Recipient-scoped lifecycle events derive a stable per-recipient id, so each recipient’s callback has its own `data.id`.
`data.occurred_at`	ISO 8601 timestamp of when the event occurred.
`data.payload`	Recipient-scoped event data. See the field table below.
`data.record_type`	Always `"event"`.
`meta.attempt`	Delivery attempt number (starts at 1).

Recipient lifecycle payload fields

Field	Type	Description
`id`	UUID	The email message id. Use this to correlate all recipients of one send, and to query the Events API.
`recipient_id`	UUID	The per-recipient row id. Unique per recipient per message — this is what makes each callback distinct.
`status`	string	The webhook event slug for this transition: `queued`, `scheduled`, `sent`, `delivered`, `deferred`, `bounced`, `failed`, `opened`, `clicked`, `unsubscribed`, `complained`, `received`, `sandbox`, `cancelled`, `daily_limit_exceeded`, or `injection_timeout`. This is the event type name, not the authoritative recipient status — for `email.bounced` the status is always `bounced` even when the recipient row is `expired` or `failed`. Use `error_evidence.code` (the 30xxx taxonomy) to distinguish failure subtypes. The authoritative recipient status is available via `recipient_statuses` on the message or the recipient endpoints.
`occurred_at`	ISO 8601	When this recipient’s transition occurred.
`from`	object	`{email, name}` of the sender.
`to` \| `cc` \| `bcc`	object	Exactly one of these keys is present, matching this recipient’s kind. The value is a single object `{email, name, kind}` — never an array.
`subject`	string	The message subject.
`error_evidence`	object \| absent	Normalized error contract. Present only on error statuses. See below.
`errors`	array \| absent	Array form of the same normalized error. Present only on error statuses. See below.
`smtp_code`	integer \| absent	Raw SMTP status from the remote MX, preserved additively for ops triage.
`smtp_response`	string \| absent	Raw SMTP response text, preserved additively.

BCC addresses are redacted. A webhook for a BCC recipient carries a bcc key whose email is an HMAC-SHA256 sentinel of the form redacted+sha256:<16-hex>@bcc.invalid, with name: null. The sentinel is stable for the same address, so support tooling can correlate records without the plaintext address ever leaving Telnyx. You cannot recover the original BCC address from a webhook.

Error evidence on failure events

Error statuses (bounced, failed, deferred, expired, suppressed, gw_reject) carry a normalized error contract in two equivalent shapes. Prefer error_evidence for programmatic branching; errors[] mirrors the platform-wide Telnyx error array convention.

{
  "error_evidence": {
    "code": "30001",
    "message": "550 5.1.1 <user@example.com>: Recipient address rejected",
    "enhanced_code": "5.1.1",
    "source": "smtp",
    "smtp_status": 550,
    "retryable": false
  },
  "errors": [
    {
      "code": "30001",
      "title": "Hard bounce",
      "detail": "550 5.1.1 <user@example.com>: Recipient address rejected",
      "source": "smtp",
      "smtp_status": 550,
      "enhanced_code": "5.1.1",
      "retryable": false
    }
  ]
}

Field	Description
`code`	The normalized 30xxx delivery error code — never a raw SMTP status. See Asynchronous delivery errors for the full taxonomy.
`message` (`detail` in `errors[]`)	The raw SMTP response text, when the failure reached SMTP.
`enhanced_code`	The DSN enhanced status code (e.g. `5.1.1`), when the remote supplied one.
`source`	Where the failure was observed: `smtp`, `mta`, or `api`.
`smtp_status`	The raw SMTP status as an integer, or `null` for failures that never reached SMTP (queue expiry, suppression, gateway rejection).
`retryable`	Whether resubmitting the same message could succeed. Only `30002` (Deferred) is retryable.

bounce_category is an internal classification field. It does not appear in normal recipient-scoped webhook payloads and is not part of the public webhook contract. In the normal callback path it never reaches the stored event row (the correlation map does not include it). A legacy message-scoped fallback path may persist it in stored events, but the Events API sanitizer does not explicitly strip it. Do not build consumer logic that reads bounce_category from any public surface. Use error_evidence.code (the 30xxx taxonomy) to distinguish failure types programmatically — for example 30001 for a hard bounce versus 30005 for a queue expiry.

Event schemas by surface

Account polling uses a webhook-shaped event envelope. Per-message history retains its older shape plus the two additive name fields.

Surface	Shape	Scope
Outbound webhook	`data: {id, event_type, canonical_event_type, occurred_at, payload, record_type}` plus delivery `meta`	Normally one recipient per event; legacy message-scoped fallbacks can omit `recipient_id`.
Account polling (`GET /email_events`)	`data[]: {id, event_type, canonical_event_type, occurred_at, payload, recipient_id?}`	Recipient-scoped rows plus fan-out of `queued`, `sending`, `sandbox`, `cancelled`, and `daily_limit_exceeded` message events. `scheduled` remains one message-scoped stored row; legacy rows may omit `recipient_id`.
Per-message history (`GET /email_messages/{email_id}/events`)	`data[]: {type, event_type, canonical_event_type, occurred_at, payload?}`	Stored events for that message, without account polling’s recipient fan-out.

Recipient-scoped account payloads contain the message id, recipient_id, and one to/cc/bcc object. Account polling builds payload.status from the stored event name, so new sharp outcomes can expose gw_reject, injection_timeout, or expired; webhook payload statuses retain their legacy rendering. Use canonical_event_type for the outcome across surfaces. They do not contain a separate email summary with recipient arrays. Internal observability fields are removed from stored payloads; error evidence depends on what was persisted and is not guaranteed to match the webhook. Use recipient status endpoints to reconcile delivery outcomes. Message-scoped polling fallbacks can omit recipient_id; their to and cc values can be address objects, address strings, or an empty string when that field has no address, and bcc is "redacted". If the related message or recipient cannot be loaded, the minimal payload contains only id, status, and occurred_at plus any public persisted evidence. Treat from, subject, and recipient fields as optional when consuming historical or fallback rows.

Webhook configuration is owned by the email-domains service, not the Email API. The /email_domains/{domain_id}/webhooks CRUD routes are served by the Telnyx email-domains service; the Email API only resolves a sending domain’s webhook list at publish time to decide where to fan out. Because the two services version independently, treat the email-domains API reference as authoritative for these routes’ request/response schemas and error codes. See Domains & DKIM for domain setup.

Email webhooks live under the domains surface at /email_domains/{domain_id}/webhooks. A subscription requires a url and an events allowlist (at least one event type) — there is no default-to-all.

Create a webhook

curl

curl -X POST https://api.telnyx.com/v2/email_domains/123e4567-e89b-12d3-a456-426614174000/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "url": "https://example.com/webhooks/email",
    "events": ["email.sent", "email.delivered", "email.bounced"]
  }'

Response 201 Created:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "record_type": "email_webhook",
    "url": "https://example.com/webhooks/email",
    "events": ["email.sent", "email.delivered", "email.bounced"],
    "domain_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2026-06-18T12:00:00Z",
    "updated_at": "2026-06-18T12:00:00Z"
  }
}

A domain can have multiple webhooks. Each event is delivered to every webhook on that domain whose events allowlist includes the event type — so you can route different event types to different endpoints by creating separate subscriptions.

List webhooks for a domain

curl

curl https://api.telnyx.com/v2/email_domains/123e4567-e89b-12d3-a456-426614174000/webhooks \
  -H "Authorization: Bearer ***"

List responses use offset pagination (page[number], page[size]) with a meta block of { page_number, page_size, total_pages, total_results }.

Retrieve, update, and delete

Operation	Method & path	Notes
Retrieve one	`GET /email_domains/{domain_id}/webhooks/{id}`	Returns the full `EmailWebhook` object.
Update	`PATCH /email_domains/{domain_id}/webhooks/{id}`	`url` and/or `events` (optional; `domain_id` is not mutable). `events` must still have ≥1 item.
Delete	`DELETE /email_domains/{domain_id}/webhooks/{id}`	Returns `204 No Content`.

All four operations return 404 if the domain or webhook is not found; create/update return 422 on validation failure.

Event filtering per subscription

The events array on each webhook is an allowlist — Telnyx only delivers events whose type appears in that list to that webhook’s URL. To receive every event type, list all 21 published types (22 are accepted, but email.sending is never delivered). To receive only delivery confirmations and failures:

{ "events": ["email.delivered", "email.bounced", "email.failed"] }

Filtering happens before delivery: an event whose type isn’t on the allowlist is never sent to that endpoint. You can update the allowlist at any time with PATCH.

Signature verification

Telnyx signs every webhook delivery with Ed25519 public-key cryptography so you can verify that a request genuinely came from Telnyx. This is strongly recommended for production. Each webhook request includes two headers:

Header	Description
`telnyx-signature-ed25519`	Base64-encoded Ed25519 signature.
`telnyx-timestamp`	Unix timestamp of when the request was signed.

The signature is computed over the string {timestamp}|{raw_json_body}. This is the standard Telnyx webhook signing scheme — email events are delivered by the same central delivery service that signs all Telnyx webhooks.

Outbound message events are published to RabbitMQ by the email API, email.received by the inbound pipeline, and domain lifecycle events by the email-domains service. Telnyx’s central event_dispatcher service signs payloads (Ed25519 / TelnyxSigner), performs HTTP delivery with retries, and tracks delivery status. The signing and retry logic is shared across all Telnyx webhook products — email uses the identical scheme as messaging webhooks.

Get your public key

Find your public key in the Mission Control Portal under Keys & Credentials → Public Key.

Verification examples

import express from 'express';
import Telnyx from 'telnyx';

const app = express();
const telnyx = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });

// Use express.raw to get the exact request body — the signature is
// computed over the raw JSON bytes, not a re-serialized object.
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['telnyx-signature-ed25519'];
  const timestamp = req.headers['telnyx-timestamp'];
  const payload = req.body.toString('utf8');

  try {
    const event = telnyx.webhooks.constructEvent(
      payload,
      signature,
      timestamp,
      process.env.TELNYX_PUBLIC_KEY
    );
    console.log('Verified email event:', event.data.event_type);
    res.sendStatus(200);
  } catch (err) {
    console.error('Signature verification failed:', err.message);
    res.sendStatus(403);
  }
});

app.listen(5000, () => console.log('Server running on port 5000'));

from flask import Flask, request
import telnyx

app = Flask(__name__)
telnyx.api_key = "YOUR_API_KEY"
telnyx.public_key = "YOUR_PUBLIC_KEY"

@app.route('/webhooks', methods=['POST'])
def webhooks():
    payload = request.data  # raw bytes
    signature = request.headers.get('telnyx-signature-ed25519')
    timestamp = request.headers.get('telnyx-timestamp')

    try:
        event = telnyx.Webhook.construct_event(payload, signature, timestamp)
        print(f"Verified email event: {event['data']['event_type']}")
        return '', 200
    except telnyx.error.SignatureVerificationError:
        return 'Invalid signature', 403

package main

import (
	"crypto/ed25519"
	"encoding/base64"
	"fmt"
	"io"
	"net/http"
	"os"
)

func verifySignature(payload, signature, timestamp string, publicKey ed25519.PublicKey) bool {
	signedPayload := timestamp + "|" + payload
	sigBytes, err := base64.StdEncoding.DecodeString(signature)
	if err != nil {
		return false
	}
	return ed25519.Verify(publicKey, []byte(signedPayload), sigBytes)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	signature := r.Header.Get("telnyx-signature-ed25519")
	timestamp := r.Header.Get("telnyx-timestamp")

	pubKeyBytes, _ := base64.StdEncoding.DecodeString(os.Getenv("TELNYX_PUBLIC_KEY"))
	publicKey := ed25519.PublicKey(pubKeyBytes)

	if !verifySignature(string(body), signature, timestamp, publicKey) {
		http.Error(w, "Invalid signature", http.StatusForbidden)
		return
	}

	fmt.Println("Webhook verified")
	w.WriteHeader(http.StatusOK)
}

func main() {
	http.HandleFunc("/webhooks", webhookHandler)
	http.ListenAndServe(":5000", nil)
}

Verify the raw body. The signature is computed over the exact bytes Telnyx sent. Re-serializing a parsed JSON object (e.g. JSON.stringify(req.body) after body-parser) can reorder keys and break verification. Read the raw request body, as shown above.

Replay protection. Reject webhooks where telnyx-timestamp is more than 5 minutes outside your server’s clock to prevent replay attacks.

Delivery and retries

An event occurs

A message changes state or a recipient interacts, and Telnyx emits an event.

Telnyx sends a POST

The event_dispatcher service signs the payload and sends an HTTP POST to every webhook URL on the matching domain whose events allowlist includes the event type.

Your server responds

Return a 2xx status code to acknowledge receipt.

Retries on failure

If your endpoint doesn’t return 2xx, Telnyx retries the delivery. Delivery uses the standard Telnyx webhook retry behavior with backoff.

Retries, URL health checking, and delivery-status tracking are handled by the central event_dispatcher service shared across all Telnyx webhook products. Email webhooks inherit the same delivery guarantees as messaging webhooks.

Consume via polling

If you don’t have a public HTTPS endpoint — or you want to pull stored outbound message history on demand — use the Events API. Polling is built for agents, batch jobs, on-prem services, and reconciliation of outbound message events after a webhook outage. The bare stored-name fields (payload.status in account polling and deprecated type in per-message history) can return queued, deferred, scheduled, cancelled, sandbox, sending, sent, failed, delivered, bounced, complained, suppressed, rejected, opened, clicked, unsubscribed, daily_limit_exceeded, scan_deferred, quarantined, quarantine_released, quarantine_release_dispatched, quarantine_rejected, quarantine_expired, gw_reject, injection_timeout, or expired. Filters accept bare or email.-prefixed names. The suppression, scan, and quarantine names are stored polling/history outcomes, not additional webhook subscription values. Polling includes stored sending and rejected events, but excludes received and every email_domain.* event.

daily_limit_exceeded records a scheduled-send admission failure when the account has insufficient daily capacity at fire time. It is persisted and published after commit when configured. Subscribe to email.daily_limit_exceeded or poll with event_type=daily_limit_exceeded. Cancellation and system failures likewise publish after commit as email.cancelled and email.failed.

Scheduled events do not have webhook/polling event-ID parity. Polling returns the one stored message-scoped scheduled row with its stored UUID; webhook publication emits one recipient-scoped callback per recipient with a derived UUID. The derived scheduled webhook IDs do not appear in GET /email_events. Reconcile scheduled events with the message ID (payload.id), event type, and occurrence time rather than the event UUID.

List account events

GET /email_events returns events for the authenticated account, oldest-first within a time window, with cursor pagination and server-side filtering.

curl

curl "https://api.telnyx.com/v2/email_events?page_size=50&event_type=delivered,bounced&from=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer ***"

Response (200):

{
  "data": [
    {
      "id": "f3a2c1d0-1234-4abc-9def-67890abcdef0",
      "event_type": "email.delivered",
      "canonical_event_type": "email.delivered",
      "occurred_at": "2026-07-06T18:24:00.000Z",
      "recipient_id": "7c1e9a44-2f60-4d1b-9a0e-3c7b5e8d1f22",
      "payload": {
        "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
        "recipient_id": "7c1e9a44-2f60-4d1b-9a0e-3c7b5e8d1f22",
        "status": "delivered",
        "occurred_at": "2026-07-06T18:24:00.000Z",
        "from": {
          "email": "sender@example.com",
          "name": "Telnyx"
        },
        "to": {
          "email": "recipient@example.com",
          "name": null,
          "kind": "to"
        },
        "subject": "Welcome"
      }
    }
  ],
  "meta": {
    "page_size": 50,
    "time_range": {
      "from": "2026-07-01T00:00:00Z",
      "to": "2026-07-31T00:00:00Z"
    }
  }
}

Filters

Parameter	Type	Description
`page_size`	integer	Page size (default 25, clamped 1–100).
`page_cursor`	string	Opaque cursor returned in the previous page’s `meta.page_cursor`. Omit on the first request.
`event_type`	string \| string[]	Comma-separated list or repeated query param. Filters to these event types. Unknown values return no matches.
`email_id`	UUID	Filter to events for a single email message. Invalid UUIDs are silently ignored.
`from`	ISO 8601 timestamp	Include events at or after this time.
`to`	ISO 8601 timestamp	Include events at or before this time.

The event_type filter accepts bare and email.-prefixed names. Legacy filters preserve their previous coverage: failed includes stored failed, gw_reject, injection_timeout, and expired rows; bounced matches stored bounced rows without expanding to expired. A canonical filter matches its own rows plus older rows whose recorded evidence proves that outcome. Use event_type=expired to query queue expirations and inspect canonical_event_type in the response.

The message filter parameter is email_id, not message_id. Filter a single message’s events with ?email_id=<email-id>. For compatibility with the Telnyx v2 bracket convention, the service also accepts the legacy alias filter[message_id]=<email-id>, which normalizes to email_id — but note that filter[email_id] is not recognized. Unrecognized filter params are silently ignored and return unfiltered results, so a typo looks like a working query that returns everything.

Pagination and ordering

Events are ordered by occurred_at ascending, then by id. Pages are cursor-based: each response includes meta.page_cursor when more results are available, and omits the field entirely (rather than null) when you’ve reached the end of the result set. Pass that cursor as page_cursor on the next request. The response meta always includes time_range — the resolved {from, to} query window, not the timestamps of the first and last returned events. With neither bound, from defaults to 30 days ago and to is null. With only from, to is capped at 30 days after from.

Account rows expose the message ID as payload.id and the recipient correlation as recipient_id when present. They do not return the former record_type, type, email_id, or email summary fields.

Per-message event history

To get the event timeline for a single message, use GET /email_messages/{email_id}/events. This is scoped to a message you own and returns its events in chronological order.

curl

curl "https://api.telnyx.com/v2/email_messages/b0c7e8cb-6227-4c74-9f32-c7f80c30934b/events?page_size=50" \
  -H "Authorization: Bearer ***"

Response (200):

{
  "data": [
    {
      "type": "queued",
      "event_type": "email.queued",
      "canonical_event_type": "email.queued",
      "occurred_at": "2026-07-06T18:20:00.000Z"
    },
    {
      "type": "sent",
      "event_type": "email.sent",
      "canonical_event_type": "email.sent",
      "occurred_at": "2026-07-06T18:20:02.000Z"
    },
    {
      "type": "delivered",
      "event_type": "email.delivered",
      "canonical_event_type": "email.delivered",
      "occurred_at": "2026-07-06T18:20:05.000Z",
      "payload": { "recipient": "recipient@example.com" }
    }
  ],
  "meta": {
    "page_size": 50
  }
}

type is deprecated but retains the bare stored name. event_type and canonical_event_type are both email.-prefixed. Events embedded in message responses retain their existing type/occurred_at/optional payload shape. Returns 404 if the email message doesn’t exist or belongs to another account. The per-message endpoint supports page_size and page_cursor but not the event_type/from/to/email_id filters (they don’t apply — you’re already scoped to one message).

Event statistics

GET /email_events/stats returns aggregate counts and derived rates for the authenticated account over a time window.

curl

curl "https://api.telnyx.com/v2/email_events/stats?from=2026-07-01T00:00:00Z&to=2026-07-07T00:00:00Z" \
  -H "Authorization: Bearer ***"

Response (200):

{
  "data": {
    "record_type": "email_event_stats",
    "counts": {
      "queued": 12500,
      "sent": 12480,
      "delivered": 12310,
      "deferred": 42,
      "bounced": 128,
      "opened": 7800,
      "clicked": 2100,
      "complained": 4,
      "unsubscribed": 35,
      "failed": 2
    },
    "rates": {
      "delivery_rate": 98.48,
      "bounce_rate": 1.02,
      "deferred_rate": 0.34,
      "open_rate": 63.36,
      "click_rate": 26.92,
      "complaint_rate": 0.03
    },
    "time_range": {
      "from": "2026-07-01T00:00:00Z",
      "to": "2026-07-07T00:00:00Z"
    }
  }
}

Stats count 10 event types: queued, sent, delivered, deferred, bounced, opened, clicked, complained, unsubscribed, and failed. Counts and rates are recipient-level: every address in to, cc, and bcc counts separately, while repeated events of the same type for the same message and recipient count once. Partial MTA injection results count successful recipients as sent and unsuccessful recipients as failed. The Email API rejects duplicate normalized recipient addresses across to, cc, and bcc. Other polling event types (such as scheduled, cancelled, sandbox, sending, rejected, and daily_limit_exceeded) are not included in stats. The rates are percentages:

Rate	Formula
`delivery_rate`	`delivered / queued`
`bounce_rate`	`bounced / queued`
`deferred_rate`	`deferred / queued`
`open_rate`	`opened / delivered`
`click_rate`	`clicked / opened`
`complaint_rate`	`complained / delivered`

from and to are optional ISO 8601 timestamps. With neither bound, from defaults to 30 days ago and to is null; the response reports those resolved query bounds.

Polling patterns

Cursor loop (backfill or steady-state tail)

Poll GET /email_events with a from timestamp, then walk the cursor until page_cursor disappears. Because from is inclusive, persist the latest occurred_at and the event IDs seen at that timestamp. Start the next poll from the same timestamp and deduplicate the boundary events by id; using only the timestamp would reprocess them.

Python

import os
import requests

API = "https://api.telnyx.com/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}"}

def poll_events(
    since_iso,
    boundary_ids=(),
    event_types=("delivered", "bounced", "failed"),
):
    """Return new events and the next inclusive `(timestamp, IDs)` checkpoint."""
    params = {
        "page_size": 100,
        "from": since_iso,
        "event_type": ",".join(event_types),
    }
    boundary_ids = set(boundary_ids)
    events = []
    latest_at = since_iso
    latest_ids = set(boundary_ids)

    while True:
        r = requests.get(f"{API}/email_events", headers=HEADERS, params=params)
        r.raise_for_status()
        body = r.json()
        for event in body["data"]:
            occurred_at = event["occurred_at"]
            event_id = event["id"]

            # `from` is inclusive: skip events already processed at the boundary.
            if occurred_at == since_iso and event_id in boundary_ids:
                continue

            events.append(event)
            if occurred_at > latest_at:
                latest_at = occurred_at
                latest_ids = {event_id}
            elif occurred_at == latest_at:
                latest_ids.add(event_id)

        cursor = body.get("meta", {}).get("page_cursor")
        if not cursor:
            break
        params["page_cursor"] = cursor

    return events, latest_at, latest_ids

# Persist both checkpoint values after processing `events`, then pass them back
# on the next run:
# events, since_iso, boundary_ids = poll_events(since_iso, boundary_ids)

When to poll vs. webhook

Use polling when…	Use webhooks when…
You have no public HTTPS endpoint (agents, on-prem, behind NAT).	You want real-time push with no polling latency.
You run a batch job that reconciles state on a schedule.	You need to react to events within seconds.
You’re reconciling stored outbound message events after a webhook endpoint was down.	Your endpoint is always reachable and can keep up with volume.
You want to inspect historical events without storing every webhook.	You want Telnyx to handle retries and delivery status.

Use webhooks for real-time reactions and polling to reconcile the overlapping stored outbound message events. Polling does not backfill email.received or email_domain.* webhooks, and it additionally exposes stored sending and rejected events without webhook delivery. Cancellation and daily-limit events support both polling and webhook subscriptions.

Choosing and combining both

Most production setups use both surfaces together:

Webhooks for real-time reactions — subscribe each domain to the event types your app cares about (email.delivered, email.bounced, email.complained are the common minimum). Verify signatures, return 2xx fast, and process asynchronously. Remember each callback is one recipient: key your handler on payload.recipient_id, not on payload.id.
Polling for reconciliation and backfill — run a periodic GET /email_events (or GET /email_events/stats for dashboards) to recover overlapping stored outbound message events missed during webhook downtime and to compute aggregate metrics. It cannot recover email.received or email_domain.* webhooks, and error evidence is limited to what was stored.
Per-message lookups for support — use GET /email_messages/{email_id}/events to show a single message’s delivery timeline on demand.
The inbound WebSocket for received mail — use /email_events/ws only for inbound email.received streaming; it carries no outbound delivery events.

Keep your webhook events allowlist tight. Subscribing to every event type is valid, but most applications only need a handful — filtering at the subscription reduces your endpoint’s load and the noise you have to sift through. Because delivery webhooks are recipient-scoped, a broad allowlist on a large multi-recipient send multiplies your callback volume by the recipient count.

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

Email Webhooks & Events

Prerequisites

Event model

Lifecycle of a message

Event names and compatibility

Webhook event-type reference

Message lifecycle (`email.*`)

Engagement & tracking (`email.*`)

Domain lifecycle (`email_domain.*`)

Consume via webhooks

Webhook payload envelope

Recipient lifecycle payload fields

Error evidence on failure events

Event schemas by surface

Create a webhook

List webhooks for a domain

Retrieve, update, and delete

Event filtering per subscription

Signature verification

Get your public key

Verification examples

Delivery and retries

Consume via polling

List account events

Filters

Per-message event history

Event statistics

Polling patterns

Cursor loop (backfill or steady-state tail)

When to poll vs. webhook

Choosing and combining both

​Prerequisites

​Event model

​Lifecycle of a message

​Event names and compatibility

​Webhook event-type reference

​Message lifecycle (email.*)

​Engagement & tracking (email.*)

​Domain lifecycle (email_domain.*)

​Consume via webhooks

​Webhook payload envelope

​Recipient lifecycle payload fields

​Error evidence on failure events

​Event schemas by surface

​Subscribe to events (webhook CRUD)

​Create a webhook

​List webhooks for a domain

​Retrieve, update, and delete

​Event filtering per subscription

​Signature verification

​Get your public key

​Verification examples

​Delivery and retries

​Consume via polling

​List account events

​Filters

​Pagination and ordering

​Per-message event history

​Event statistics

​Polling patterns

​Cursor loop (backfill or steady-state tail)

​When to poll vs. webhook

​Choosing and combining both

Prerequisites

Event model

Lifecycle of a message

Event names and compatibility

Webhook event-type reference

Message lifecycle (`email.*`)

Engagement & tracking (`email.*`)

Domain lifecycle (`email_domain.*`)

Consume via webhooks

Webhook payload envelope

Recipient lifecycle payload fields

Error evidence on failure events

Event schemas by surface

Subscribe to events (webhook CRUD)

Create a webhook

List webhooks for a domain

Retrieve, update, and delete

Event filtering per subscription

Signature verification

Get your public key

Verification examples

Delivery and retries

Consume via polling

List account events

Filters

Pagination and ordering

Per-message event history

Event statistics

Polling patterns

Cursor loop (backfill or steady-state tail)

When to poll vs. webhook

Choosing and combining both