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 three related surfaces: webhooks (push, real time, recipient-scoped), message-event polling (pull, on demand, mixed cardinality), and an inbound WebSocket (push, real time, inbound only). 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 event taxonomies and payload shapes are not identical — 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`

There is no email.expired webhook event type — expired is a recipient status, not an event type. 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 19 event types: 13 outbound/tracking email.* events handled by the email API (12 published plus email.sending which is accepted but never delivered), email.received published by the inbound pipeline, and 5 email_domain.* domain-lifecycle events published by the domains service. This is the complete webhook subscription allowlist. The polling API uses a separate 16-type message-event taxonomy described under Consume via polling.

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 18 of the 19 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.	`scheduled_at` timestamp.
`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.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.

The five email_domain.* events are emitted by the Telnyx email-domains service, email.received is emitted by the inbound pipeline, and the other thirteen email.* events are handled by the email API (twelve are published as webhooks; email.sending is accepted by the subscription schema but never delivered). A webhook subscription can span the full 19-type allowlist; only 18 types are actually delivered. GET /email_events stores and returns only its separate outbound message-event taxonomy; it does not return domain lifecycle events or email.received.

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",
    "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 18 published webhook event types above (`email.sending` is accepted but never delivered).
`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`, or `sandbox`. 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

The three consumption surfaces do not share a schema. They differ in cardinality (one event per recipient for webhooks versus mixed cardinality for the Events API) and in field set. Do not write a single parser that assumes all three are interchangeable.

Surface	Cardinality	Shape	Carries `error_evidence`
Recipient lifecycle webhook	One event per recipient per transition	`data.payload` with `recipient_id` and a single `to`/`cc`/`bcc` object	Yes, on error statuses
Events API (`GET /email_events`)	Mixed cardinality: message-scoped admission events and per-recipient delivery/engagement transitions	`{id, type, occurred_at, email_id, email, payload}` where `email` is a message summary with recipient arrays. Recipient transitions produce multiple rows per message even though the response does not expose `recipient_id`.	No — internal fields are stripped before the response
Inbound WebSocket (`/email_events/ws`)	One frame per inbound message	`{event_type, account_id, inbox_id, occurred_at, payload}`	Not applicable (inbound only)

The Events API strips observability-only and internal fields from the stored event payload before returning it. Fields you see in a webhook — including error_evidence — are not guaranteed to be present in the Events API response. Treat the webhook as the source of delivery-failure detail.

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 the deleted webhook in `data`.

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 18 published types (19 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 polling model accepts these 16 bare event types: queued, deferred, scheduled, cancelled, sandbox, sending, sent, failed, delivered, bounced, complained, rejected, opened, clicked, unsubscribed, and daily_limit_exceeded. Unlike webhook subscriptions, polling includes sending, cancelled, rejected, and daily_limit_exceeded, but excludes received and every email_domain.* event.

daily_limit_exceeded is a scheduled-send admission failure, not a webhook subscription event. It is persisted when a scheduled send fires and the account’s daily send limit no longer has room for it — the message is rejected at fire time rather than at submission time. It cannot be selected in a webhook events allowlist; poll for it or query it via filter[event_type]=daily_limit_exceeded.

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": [
    {
      "record_type": "email_event",
      "id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
      "type": "delivered",
      "occurred_at": "2026-07-06T18:24:00.000Z",
      "email_id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
      "email": {
        "from": { "email": "sender@example.com", "name": "Telnyx" },
        "to": [{ "email": "recipient@example.com" }],
        "cc": [],
        "subject": "Welcome"
      },
      "payload": { "recipient": "recipient@example.com" }
    }
  ],
  "meta": {
    "page_size": 50,
    "time_range": {
      "from": "2026-07-01T00:00:00Z",
      "to": "2026-07-31T00:00:00Z"
    },
    "page_cursor": "eyJvY2N1cnJlZF9hdCI6IjIwMjYtMDctMDZUMTg6MjQ6MDBaIn0="
  }
}

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 the bare event names (e.g. delivered, bounced, opened) — not the email.-prefixed webhook event types. So event_type=delivered,bounced filters to delivery and bounce events.

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.

The email summary block ({from, to, cc, subject}) is present when the underlying message is available for preload, and omitted (not null) when it isn’t. Don’t rely on it always being present — guard for its absence.

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",
      "occurred_at": "2026-07-06T18:20:00.000Z"
    },
    {
      "type": "sent",
      "occurred_at": "2026-07-06T18:20:02.000Z"
    },
    {
      "type": "delivered",
      "occurred_at": "2026-07-06T18:20:05.000Z",
      "payload": { "recipient": "recipient@example.com" }
    }
  ],
  "meta": {
    "page_size": 50
  }
}

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 sending, cancelled, rejected, and daily_limit_exceeded message events that cannot be selected in a webhook subscription.

Consume via WebSocket (inbound only)

GET /email_events/ws upgrades to an authenticated WebSocket that streams inbound email in real time.

The WebSocket is inbound-only. It streams email.received events for messages arriving at your enabled inbound domains. It does not carry outbound delivery lifecycle events — you will never receive email.delivered, email.bounced, email.deferred, or any tracking event on this socket. To consume outbound delivery events, use webhooks or the Events API.

Subscription is account-scoped. On connect the server pushes a connected frame naming the account and the active filter:

{ "event_type": "connected", "account_id": "...", "inbox_id": null }

Each matching inbound event then arrives as a single JSON text frame:

{
  "event_type": "email.received",
  "account_id": "...",
  "inbox_id": "...",
  "occurred_at": "2026-07-24T12:00:00Z",
  "payload": { }
}

Send {"type":"ping"} to receive {"event_type":"pong"}. Native WebSocket ping/pong control frames are handled by the server automatically. Any other client frame is answered with an error frame; unparseable frames never close the connection. Pass an optional inbox_id query parameter to filter to a single inbox — a non-UUID value is rejected with code 10002.

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 it does not return error_evidence.
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

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

Email Webhooks & Events

Prerequisites

Event model

Lifecycle of a message

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

Consume via WebSocket (inbound only)

Choosing and combining both

​Prerequisites

​Event model

​Lifecycle of a message

​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

​Consume via WebSocket (inbound only)

​Choosing and combining both

Prerequisites

Event model

Lifecycle of a message

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

Consume via WebSocket (inbound only)

Choosing and combining both