Email Event Lifecycle

When you POST /v2/email_messages, Telnyx returns 202 Accepted — not “delivered”. Everything that matters after that point happens asynchronously, over seconds to days, and is reported to you as a stream of events. This page explains the conceptual model behind that stream: what states a message passes through, what causes each transition, which event fires, and what gets recorded. It is a companion to the Webhooks & Events how-to guide, which covers the mechanics of subscribing, verifying signatures, and polling. Read that one to wire things up; read this one to understand what you’re seeing.

The single most important idea on this page: delivery state is tracked per recipient, not per message. A message to three recipients is three independent lifecycles that can end in three different states. Every webhook event you receive describes exactly one recipient.

The two-layer model

Telnyx tracks an outbound email at two levels, and conflating them is the most common source of confusion.

Layer	What it tracks	Values written by the outbound path
Message (`email_messages.status`)	Request lifecycle — did we accept and process your API call?	`queued`, `scheduled`, `sandbox`, `sending`, `completed`, `cancelled`, `failed`
Recipient (`email_recipients.status`)	Delivery outcome — what happened to this one address?	`queued`, `sent`, `gw_reject`, `deferred`, `delivered`, `bounced`, `failed`, `expired`, `cancelled`, `injection_timeout`

The message layer answers “did Telnyx take the job?”. The recipient layer answers “did the mail arrive?”. A message reaches completed when every one of its recipients has reached a terminal state — completed means finished, not delivered. The message layer moves to failed only on a pre-dispatch rejection that stops the whole request, such as a scheduled send that exceeds your daily send limit at fire time. Transport outcomes — delivered, bounced, deferred — are never written onto the message row.

Treat the message-level values as a description of current behavior, not a frozen enum. The authoritative delivery state is always the recipient row, and that is what every delivery webhook and every Email Detail Record describes. Build your logic on the recipient layer.

The recipient status sending exists in the schema and the transition table, but the current outbound path never writes it — recipients go from queued straight to an injection outcome. Don’t build branching that waits to observe it.

The lifecycle

An email is handed to KumoMTA, the outbound mail transfer agent. Telnyx injects the message over HTTP, and KumoMTA reports back asynchronously with log records — one per event, per recipient. Those records drive the state machine.

Per-recipient states

Callbacks are not ordered, so queued also accepts a Delivery, TransientFailure, Bounce, OOB, AdminBounce, or Expiration that arrives before the injection outcome is recorded — going straight to delivered, deferred, bounced, failed, or expired respectively. Terminal states are delivered, bounced, failed, expired, gw_reject, cancelled, and injection_timeout. Once a recipient is terminal it does not regress — a late TransientFailure arriving after a delivered is logged for diagnostics and ignored, never applied. There is exactly one deliberate exception: injection_timeout → sent. See Ambiguous injection below.

The message-level track

The parent message runs on its own short track, and it is not part of the per-recipient state machine above: When the consumer picks the message up it sets the message to sending and records a message-scoped sending event. That event is stored but deliberately does not publish a webhook — the per-recipient webhooks are published separately once the MTA responds. Recipient rows stay queued throughout; they only move once injection is accepted, refused, times out, or a callback arrives.

What each recipient state means

queued — accepted, not yet handed to the MTA

The API validated your request, persisted the message, and returned 202. Nothing has been transmitted yet.Fires: email.queued (also email.scheduled for a future send_at, or email.sandbox in sandbox mode — neither attempts delivery).Not yet billable. Acceptance by our API is not acceptance by the MTA.

sent — KumoMTA accepted the recipient into its queue

The message is now the MTA’s responsibility. It will attempt delivery to the recipient’s MX, retrying on transient failures.Fires: email.sent on a successful HTTP injection. A Reception callback also lands the recipient here but does not publish a duplicate event.Billable from this point — queue acceptance is the billing trigger.sent does not mean the recipient received it. Remote acceptance is reported separately as email.delivered.

delivered — the receiving server accepted the message

KumoMTA got a 250 OK from the recipient’s MX. This is the successful terminal state.Fires: email.delivered. EDR records: delivered_at.Delivered means accepted by the receiving server — it does not guarantee inbox placement. The mail can still be filed as spam by the recipient’s provider after acceptance, which is invisible to SMTP. See Deliverability.

deferred — temporary failure, will retry

The receiving server returned a 4xx transient response (greylisting, rate limiting, “try again later”). KumoMTA backs off and retries.Fires: email.deferred. EDR records: deferred_at, plus error_evidence carrying code 30002.A recipient can be deferred many times before resolving. deferred_at is stamped on the first deferral and locked — it is not a “most recent attempt” field. Repeated deferrals for the same address escalate an internal soft-bounce counter, which can eventually auto-suppress the address as a hard bounce.

bounced — permanent rejection by the receiver

The receiving server refused the message outright (5xx), or an asynchronous bounce report arrived after the fact.Fires: email.bounced. EDR records: bounced_at and error_evidence (code 30001, or 30002 when KumoMTA reports a bounce carrying a 4xx code).Bounces with a 5.1.x or 5.2.x enhanced code (bad or disabled mailbox) auto-suppress the address. Bounces with 5.7.x (sender policy/authentication) do not — the address may be perfectly valid, and the problem is on your side.

expired — KumoMTA exhausted its retry window

The MTA retried until its queue expiry deadline and gave up. Nothing about the recipient address was rejected; the remote server simply never accepted the message in time.Fires: email.bounced — the webhook event type for the Expiration callback is still the canonical bounce type. EDR records: expired_at, expired: true, and error_evidence with code 30005 (Queue expiry, source mta).Billable — the message was accepted into the MTA queue, which is the billing trigger.Expiration is provisionally treated as a hard bounce for suppression purposes.

failed — non-delivery caused by us or an operator

Distinct from bounced and expired: nothing about the recipient address was rejected and the MTA did not run out of retries. Either an internal/system failure occurred (e.g. the message could not be published to the send pipeline, or the account became ineligible before dispatch), or an operator cancelled the in-flight message (AdminBounce).Fires: email.bounced on the AdminBounce callback path. System failures insert a stored failed event but do not publish an email.failed webhook — see System failures.EDR records: failed_at and error_evidence (code 30003 when an SMTP status is present, otherwise 30099).Because failed is not a recipient-side signal, it does not suppress the address.

gw_reject — KumoMTA refused the injection

The MTA rejected the message at the HTTP injection boundary, before it ever entered a queue. This is pre-queue, so it is never billable.Fires: email.failed. EDR records: error_evidence and errors[] with code 30006 (Gateway rejection, source api).

injection_timeout — we genuinely do not know

The injection HTTP call timed out with no response. KumoMTA may or may not have accepted the message.Fires: email.injection_timeout. Not billable. No EDR is published — the outcome is ambiguous, and a later Reception callback would publish one on reconciliation.See Ambiguous injection.

cancelled — withdrawn before it was queued

A scheduled or queued message was cancelled before injection. Only queued and sending recipients can be cancelled; anything already accepted by the MTA is past the point of recall and is left untouched. Never billable.

How MTA callbacks map to events

KumoMTA emits typed log records. Each record type maps to exactly one canonical event type, and — separately — drives the recipient state machine.

KumoMTA record	Webhook published	Recipient status	Stored event type	Internal `bounce_category`
`Reception`	— (no duplicate event)	`sent`	`queued`	—
`Delivery`	`email.delivered`	`delivered`	`delivered`	—
`TransientFailure`	`email.deferred`	`deferred`	`deferred`	—
`Bounce`	`email.bounced`	`bounced`	`bounced`	`permanent`
`OOB`	`email.bounced`	`bounced`	`bounced`	`oob`
`Expiration`	`email.bounced`	`expired`	`failed`	`transient`
`AdminBounce`	`email.bounced`	`failed`	`failed`	`admin`
`Feedback`	`email.complained`	(no change)	`complained`	—

bounce_category is an internal classification and is not part of any public contract. It is computed during callback handling and drives auto-suppression, but it is not forwarded into the published webhook, and it is never written into the recipient-scoped event row that GET /v2/email_events returns — that row’s payload is built from correlation fields plus the recipient address only. Do not build consumer logic that reads it from either surface — use error_evidence.code to distinguish failure modes.

Expiration diverges three ways, and you need all three to reason about it.

The webhook event type is email.bounced — the canonical bounce family type.
The recipient status (and therefore the EDR status) is expired, with expired_at and error code 30005.
The stored event type returned by GET /v2/email_events is failed — the polling taxonomy has no expired member.

Only AdminBounce maps the recipient to failed. Bounce and OOB map to bounced. If you are building suppression or list-hygiene logic, treat permanent and oob as recipient signals; treat transient and admin as operational signals about your sending, not about the address.

The status field inside a webhook payload is the event type, not the recipient status. An expired recipient produces a payload with "status": "bounced" while its EDR reads "status": "expired". Read error_evidence.code to tell the failure modes apart: 30001 is a hard bounce, 30005 is queue expiry, 30003/30099 are system failures, 30006 is a gateway rejection.

Reception callbacks

email.queued fires from two different places, meaning two different things:

API acceptance — we persisted your request. The recipient stays queued. Pre-queue, not billable.
KumoMTA Reception — the MTA logged reception of the message. This moves the recipient to sent and is billable. No duplicate email.queued event is published — the API-level event already recorded acceptance.

Count sends using email.sent webhooks. A Reception callback updates the recipient to sent and billable, but does not publish a duplicate email.queued event — the API-level email.queued event already recorded acceptance. Counting email.sent is sufficient.Count from the recipient EDR instead — billable: true, or a non-null sent_at — or use GET /v2/email_events/stats, which aggregates at the recipient level. If you derive counts from the raw event stream, count email.sent events — each represents one accepted recipient.

System failures: stored, but not pushed

When the message cannot be handed to the send pipeline at all — a publish failure into the send queue after the request has already been committed, or an account that became ineligible before a scheduled send fires — every still-non-terminal recipient is driven to failed and a stored failed event is written for each one. That path does not publish an email.failed webhook, and it does not publish an EDR either — mark_system_failure updates the recipient rows and inserts stored events directly, without invoking the EDR publisher. For a failure before queue acceptance there may be no EDR at all; for a recipient already accepted, the existing EDR is not updated to reflect the failure. If you rely exclusively on webhooks, these failures are invisible. Reconcile with GET /v2/email_events or the authoritative per-recipient status endpoint — not the EDR. The email.failed webhook is published for a definite injection refusal by the MTA (recipient status gw_reject, error code 30006). System failures also do not blanket-reset billability. The transition is permitted from queued, sending, sent, and deferred; a recipient that had already been accepted into the MTA queue (sent or deferred) keeps its billable: true, because the message really was transmitted. Only pre-queue recipients (queued, sending) end up non-billable.

Complaints are additive, not a state change

email.complained fires when a mailbox provider forwards an ARF spam report (the recipient hit “mark as spam”). By definition this arrives after delivery. It does not move the recipient out of delivered or bounced — the delivery already happened, and that fact is not retracted. The complaint is recorded alongside it and auto-suppresses the address. Because it is a no-op for the state machine, it does not produce a new EDR.

Ambiguous injection: the honest unknown

If the injection call times out, retrying risks delivering the message twice; not retrying risks losing it. Telnyx chooses loss over duplication — the industry-standard trade-off for transactional mail. The recipient moves to the terminal injection_timeout state and email.injection_timeout fires. If KumoMTA did accept the message, its Reception callback arrives moments later and reconciles the recipient forward to sent, from where the normal lifecycle resumes. This is the only terminal-to-non-terminal edge in the entire state machine, and it is safe precisely because the callback is authoritative proof of acceptance.

email.injection_timeout is a webhook-only event type. It is not part of the stored event taxonomy returned by GET /v2/email_events, and the underlying recipient transition is recorded as failed in the persisted event row. If you rely on polling rather than webhooks, ambiguous injections surface as failures.

Event reference

Event	Trigger	Recipient status	EDR timestamp	Billable
`email.queued`	API accepted the request	`queued` → `sent`	`created_at`	No (API acceptance is not billable)
`email.scheduled`	Accepted with a future `send_at`	`queued`	`scheduled_at`	No
`email.sandbox`	Accepted in sandbox mode; no delivery attempted	`queued`	`created_at`	No (`billable` forced false)
`email.sent`	KumoMTA accepted the HTTP injection	`sent`	`sent_at`	Yes
`email.delivered`	KumoMTA `Delivery` (250 from remote MX)	`delivered`	`delivered_at`	Yes
`email.deferred`	KumoMTA `TransientFailure` (4xx)	`deferred`	`deferred_at` (first deferral)	Yes
`email.bounced`	KumoMTA `Bounce` / `OOB`	`bounced`	`bounced_at`	Yes
`email.bounced`	KumoMTA `Expiration`	`expired`	`expired_at`	Yes
`email.bounced`	KumoMTA `AdminBounce`	`failed`	`failed_at`	Yes
`email.complained`	KumoMTA `Feedback` (ARF report)	unchanged	—	Unchanged
`email.failed`	KumoMTA refused the injection	`gw_reject`	—	No
`email.injection_timeout`	Ambiguous transport timeout on injection	`injection_timeout`	—	No
`email.opened`	Tracking pixel loaded	unchanged	—	No
`email.clicked`	Tracked link followed	unchanged	—	No
`email.unsubscribed`	Tracked unsubscribe link used	unchanged	—	No

A pre-dispatch system failure produces a stored failed event with no corresponding webhook; its billability depends on whether queue acceptance had already occurred. See System failures.

Billing is derived from the source event, never from the resulting status. A recipient is billable the moment it is proven to have been accepted into the MTA queue — by Reception, Delivery, TransientFailure, Bounce, AdminBounce, OOB, Expiration, or a successful injection.This is why a bounce is still billable: the message was transmitted; the receiver rejected it. And why gw_reject, cancelled, injection_timeout, and pre-queue system failures are never billable — nothing was ever transmitted. A message that fails on our side before reaching the queue costs you nothing.

Bounce categories

Bounce-family callbacks are classified with a bounce_category:

Category	Meaning	Recipient status	Auto-suppresses?
`permanent`	Hard bounce — 5xx from the receiving MX (mailbox not found, domain invalid)	`bounced`	Yes, on `5.1.x` / `5.2.x`
`oob`	Out-of-band — an asynchronous bounce report arriving after the message left our system	`bounced`	Yes, on `5.1.x` / `5.2.x`
`transient`	KumoMTA exhausted its retry window and gave up (`Expiration`)	`expired`	Yes (provisional)
`admin`	Operator-initiated bounce (`AdminBounce`)	`failed`	No

bounce_category is internal. It is computed when the callback is handled and is used to drive auto-suppression, but it is not forwarded into the published webhook payload and not written into the recipient-scoped event row that GET /v2/email_events returns — that payload is built from correlation fields plus the recipient address only. Treat it as absent from both surfaces.Do not write handlers that branch on bounce_category on either surface. Use error_evidence.code (30001 hard bounce, 30005 queue expiry, 30003/30099 system failure, 30006 gateway rejection) together with error_evidence.enhanced_code to distinguish the failure modes. The recipient status (bounced vs expired vs failed) on the authoritative recipient-status endpoint carries the same distinction the category was standing in for.

An out-of-band bounce is the reason a delivered recipient can later become bounced: the receiving server accepted the message, then generated a bounce afterwards. It is the only correction edge out of delivered, and it is genuinely common with forwarding setups and catch-all domains.

The Email Detail Record (EDR)

The Email Detail Record is the durable, per-recipient record of what happened. Where webhooks are a real-time notification you might miss, the EDR is the system of record used for billing, support, and reconciliation. One recipient = one EDR identity. The recipient’s UUID is the stable EDR UUID, so a message to five people produces five EDR identities.

What produces an EDR — and what doesn’t

EDRs are published at three points, not on every event:

Sandbox acceptance — a provisional record per recipient (billable forced false); sandbox never enters the send pipeline, so this is its only publication point.
Injection outcomes — a provisional record for each recipient the MTA accepted, and a final record for each recipient it refused (gw_reject).
Applicable callback transitions — a Reception, Delivery, TransientFailure, Bounce, OOB, AdminBounce, or Expiration that actually moves the recipient forward.

Nothing else publishes one:

Engagement events (email.opened, email.clicked, email.unsubscribed) create stored events and webhooks but never invoke the EDR publisher.
Complaints on an already-delivered or bounced recipient are state-machine no-ops, so they produce no new record.
Ambiguous injection timeouts explicitly get no EDR — the outcome is unknown. If a late Reception reconciles the recipient to sent, that transition publishes the provisional record.
Pre-dispatch system failures write stored events and update recipient rows directly; they do not publish an EDR.

Provisional and final records

For a recipient accepted by the MTA, the first record is provisional — a unique-per-recipient rating intent, so a pipeline replay cannot create a second one. Every subsequent lifecycle transition (deferred, delivered, OOB, bounce, expiry) publishes an append-only final record: a new row that carries the same recipient UUID as its stable EDR identity. Records are never rewritten in place.

A refused recipient starts final, not provisional. When the MTA refuses injection, the recipient goes straight to gw_reject and a single final EDR is published for it — there is no provisional record first, because there was never a rating intent to reserve. Do not assume every EDR identity begins with a provisional row.

Lifecycle fields

Field	Meaning
`status`	Current lifecycle state — the field you want. One of `queued`, `sending`, `sent`, `deferred`, `delivered`, `bounced`, `failed`, `expired`, `suppressed`, `cancelled`, `gw_reject`
`created_at`	API acceptance time
`sent_at`	Queue acceptance by the MTA
`delivered_at`	Remote MX accepted
`deferred_at`	First transient failure
`bounced_at`	Permanent rejection
`failed_at`	System/operator non-delivery
`expired_at`	MTA retry window expired
`suppressed_at`	Recipient was suppressed before sending
`completed_at`	First terminal outcome
`attempt_count`	Delivery attempts made
`expired` / `suppressed`	Booleans mirroring the terminal condition
`billable`	Whether this recipient counts toward usage

Every lifecycle timestamp is set-once: it locks on first acceptance, and a later record that tries to overwrite a stamped value is rejected. That is why deferred_at is the first deferral rather than the most recent one — a retry never rewrites it, and it never rewrites sent_at either.

delivery_status is not the lifecycle state. Despite the name, the EDR’s delivery_status field is a fixed platform-level field currently emitted as "not_configured". Read status for the delivery outcome. Filtering or branching on delivery_status will not do what you expect.

Error fields

Two structured fields carry failure detail, and both use the normalized 30xxx error taxonomy — not raw SMTP codes. Raw SMTP codes vary per remote MX, collide across unrelated failure modes, and are absent entirely for failures that never reached SMTP (queue expiry, suppression, gateway rejection). The EDR therefore carries a product-level code and preserves the raw SMTP status alongside it as smtp_status.

The 30xxx taxonomy

Code	Title	`source`	`retryable`	Raised when
`30001`	Hard bounce	`smtp`	`false`	`bounced` with a 5xx code, or a bounce with no usable code
`30002`	Deferred	`smtp`	`true`	`deferred`, or `bounced` carrying a 4xx code
`30003`	Injection failure	`mta`	`false`	`failed` with an SMTP status — the MTA refused the injection
`30004`	Suppressed recipient	`api`	`false`	`suppressed` — the address was on the suppression list
`30005`	Queue expiry	`mta`	`false`	`expired` — the retry window elapsed
`30006`	Gateway rejection	`api`	`false`	`gw_reject` — refused at the HTTP injection boundary
`30099`	Internal error	`api`	`false`	`failed` without an SMTP status — nothing reached the MTA

`error_evidence`

Six fields. Required on every error status: bounced, failed, deferred, expired, suppressed, gw_reject. Omitted entirely on success statuses.

{
  "error_evidence": {
    "code": "30001",
    "message": "5.1.1 The email account that you tried to reach does not exist",
    "enhanced_code": "5.1.1",
    "source": "smtp",
    "smtp_status": 550,
    "retryable": false
  }
}

Key	Type	Meaning
`code`	string	Normalized 30xxx taxonomy code. Never a raw SMTP code — a record carrying `"550"` here is rejected before publication
`message`	string \| null	Diagnostic text from the receiving server. Required when `source` is `smtp`; null for failures that never reached a remote host
`enhanced_code`	string \| null	RFC 3463 enhanced status code in `X.Y.Z` form (`"5.1.1"`)
`source`	string	Where the failure originated: `smtp`, `mta`, `api`, `dns`, `dkim`, or `spam`
`smtp_status`	integer \| null	The raw SMTP status code, preserved for ops triage (`550`, `421`)
`retryable`	boolean	Whether retrying this address could succeed

`errors[]`

Seven fields per entry. Non-empty for every error status, empty for success statuses.

{
  "errors": [
    {
      "code": "30001",
      "title": "Hard bounce",
      "detail": "5.1.1 The email account that you tried to reach does not exist",
      "source": "smtp",
      "smtp_status": 550,
      "enhanced_code": "5.1.1",
      "retryable": false
    }
  ]
}

Key	Type	Meaning
`code`	string	Normalized 30xxx code — structurally required
`title`	string	Human-readable taxonomy title (`"Hard bounce"`, `"Queue expiry"`) — structurally required
`detail`	string \| null	Diagnostic text. This field is named `detail`, not `message`
`source`	string	`smtp`, `mta`, `api`, `dns`, `dkim`, or `spam` — structurally required
`smtp_status`	integer \| null	Raw SMTP status code when one exists
`enhanced_code`	string \| null	Enhanced status code when one exists
`retryable`	boolean	Structurally required

code, title, source, and retryable are present on every entry. detail, smtp_status, and enhanced_code legitimately stay null for failures that never reached SMTP — fabricating a response string would be worse than leaving it empty.

Webhook payloads

Webhook payloads are not a projection of the full EDR. They are built from a compact recipient-scoped shape:

{
  "id": "8f2b1c34-...",
  "recipient_id": "6c0a9d51-...",
  "status": "bounced",
  "occurred_at": "2026-07-24T12:00:00.000000Z",
  "from": { "email": "you@yourdomain.com", "name": "Your App" },
  "subject": "Your receipt",
  "to": { "email": "user@example.com", "name": null, "kind": "to" }
}

Field	Meaning
`id`	The message ID
`recipient_id`	The durable recipient row UUID — your join key
`status`	The event type (`queued`, `sent`, `delivered`, `bounced`, `deferred`, `failed`, `injection_timeout`, …), not the recipient’s internal status
`occurred_at`	When the event occurred
`from`	Sender address and display name
`subject`	Message subject
`to` / `cc` / `bcc`	Exactly one recipient projection — `{email, name, kind}`. The key names which envelope field this recipient came from. BCC addresses are redacted to a stable HMAC sentinel

On error events (bounced, failed, deferred, expired, suppressed, gw_reject recipient statuses) the payload additionally carries error_evidence and errors[]. Scheduled sends add send_at; ambiguous-injection events add ambiguous_timeout: true.

The raw smtp_code / smtp_response compatibility fields are conditional. They are present only when the failure carries callback-driven SMTP evidence — a Bounce, TransientFailure, OOB, AdminBounce, or Expiration record from KumoMTA that actually reached the wire.Failures raised before SMTP was ever spoken carry no smtp_code or smtp_response at all. Injection refusals (gw_reject, code 30006) build their payload from the normalized error contract only: error_evidence and errors[], with smtp_status and message explicitly null. Treat error_evidence as the field you branch on, and both raw SMTP fields as optional extras that may be absent entirely.

What a webhook payload does not contain. Billing fields (billable, sandbox), EDR lifecycle timestamps (sent_at, delivered_at, bounced_at, expired_at, …), SMTP-host evidence (sending_ip, mx_hostname, mx_ip), tags, and bounce_category are not forwarded into the published webhook.These fields are not uniformly recoverable elsewhere. Billing fields, lifecycle timestamps, and SMTP-host evidence live on the EDR. bounce_category is internal: it is not on the webhook, and it is not written into the recipient-scoped event row that GET /v2/email_events returns. The stored event returned by that endpoint carries a sanitized payload — internal correlation fields are stripped before it is returned — so it is not a full EDR replacement.Null values are not stripped — "name": null is sent as an explicit null. Handle nulls rather than assuming key absence.If you need the full record, use the authoritative per-recipient status endpoint or the EDR — not a recipient_id join against GET /v2/email_events, whose public payload omits the internal recipient identifiers.

Consuming the lifecycle

Three surfaces expose the outbound lifecycle. Pick based on your infrastructure — but note that they do not carry identical fields (see the warning above).

Surface	Endpoint	Use when
Webhooks	Your HTTPS endpoint	You want push delivery in real time and can host a public endpoint
Polling	`GET /v2/email_events`	You have no public endpoint, or you’re reconciling after an outage. Returns a sanitized payload — internal correlation fields are stripped, and `bounce_category` is not present
Stats	`GET /v2/email_events/stats`	You want aggregate recipient-level counts and rates, not individual events

The WebSocket endpoint is inbound-only. is a best-effort real-time stream of inbound email.received events for your account. It does not carry the outbound delivery lifecycle — no email.sent, email.delivered, email.bounced, or any other outbound event is broadcast on it. Use webhooks or polling for outbound.

Webhooks fire per event, per recipient, and each subscription carries an allowlist — you receive only the event types you asked for. A subscription listing only email.bounced gets bounces and nothing else. See the Webhooks & Events guide for subscription setup, payload envelopes, Ed25519 signature verification, cursor pagination, and retry behavior.

The polling API and the webhook allowlist use different taxonomies. Polling filters accept bare event names (delivered, bounced); webhook subscriptions use the prefixed form (email.delivered). The stored taxonomy has no expired or injection_timeout member — both are recorded as failed — and it excludes webhook-only types such as email.injection_timeout entirely. Don’t assume a name valid in one is valid in the other.

Designing a consumer

A few properties of the stream are worth designing around: Events are not ordered. A Delivery callback can arrive before the Reception that logically precedes it. The state machine handles this — queued → delivered is a legal edge — and your consumer should too. Use the timestamps, not arrival order. Events are idempotent, and replays happen. The same callback redelivered produces no second state transition and no duplicate stored event. Your handler should be equally tolerant: key on the event ID. Terminal is not always final. delivered → bounced via an out-of-band report is legitimate and will happen in production. Don’t build logic that assumes a delivered message can never bounce. Scope everything by recipient. A three-recipient message produces three parallel event streams. Aggregating them into one message-level status will lose information the moment one recipient bounces and another delivers. Don’t count from webhooks alone. Some outcomes are stored without a webhook (pre-dispatch system failures), and one webhook type covers several statuses (email.bounced for bounced, expired, and admin-bounced). Reconcile against GET /v2/email_events, the stats API, or the authoritative per-recipient status endpoint. Note that system failures do not publish an EDR, so the EDR alone will not close that gap.

Delivery failures come in two layers

When something goes wrong, the layer tells you where to look.

Layer 1 — API errors (`10xxx`)

The request was rejected synchronously. No message was created, no event fires, nothing is billed. You get an HTTP error with a Telnyx error code — 10015 for validation failures, 10007 for an unverified domain or unauthorized sender, 10006 for a bad API key. These are your bugs, and they are fixable before you retry. Full list in the Error codes reference.

Layer 2 — Delivery failures (`30xxx`)

The request succeeded and delivery failed downstream. These surface asynchronously as events, and the detail lives in error_evidence:

error_evidence.code — the normalized taxonomy code ("30001", "30002", "30005"), never a raw SMTP code
error_evidence.source — where it originated (smtp, mta, api, …)
error_evidence.retryable — whether retrying this address could succeed
error_evidence.smtp_status — the raw SMTP status, preserved for triage (550, 421)
error_evidence.enhanced_code — the RFC 3463 enhanced status code ("5.1.1")
error_evidence.message — what the receiving server actually said (null when nothing reached SMTP)

Route on code and retryable, triage on smtp_status and enhanced_code. 30002 is temporary (you’ll see email.deferred, and the MTA is already retrying — do nothing). 30001 is permanent (you’ll see email.bounced, and retrying the same address will fail again). 30005 means we ran out of retry window, and 30003/30006/30099 mean the failure was on our side of the wire, not the recipient’s. Within a hard bounce, the enhanced code tells you whose problem it is. 5.1.x and 5.2.x are recipient problems — bad or full mailbox, and the address is auto-suppressed. 5.7.x is a sender problem — authentication or policy rejection — and the address is deliberately not suppressed, because it is probably fine. A rise in 5.7.x means you should be checking SPF, DKIM, and DMARC, not cleaning your list.

Webhooks & Events — subscribe, verify signatures, poll, paginate
Error codes — the full API error reference
Deliverability — reputation, authentication, and bounce handling
Suppressions — how auto-suppression works and how to manage the list
Send an email — the send API and its fields

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

For AI Agents

Email Event Lifecycle

The two-layer model

The lifecycle

Per-recipient states

The message-level track

What each recipient state means

How MTA callbacks map to events

Reception callbacks

System failures: stored, but not pushed

Complaints are additive, not a state change

Ambiguous injection: the honest unknown

Event reference

Bounce categories

The Email Detail Record (EDR)

What produces an EDR — and what doesn’t

Provisional and final records

Lifecycle fields

Error fields

The 30xxx taxonomy

`error_evidence`

`errors[]`

Webhook payloads

Consuming the lifecycle

Designing a consumer

Delivery failures come in two layers

Layer 1 — API errors (`10xxx`)

Layer 2 — Delivery failures (`30xxx`)

​The two-layer model

​The lifecycle

​Per-recipient states

​The message-level track

​What each recipient state means

​How MTA callbacks map to events

​Reception callbacks

​System failures: stored, but not pushed

​Complaints are additive, not a state change

​Ambiguous injection: the honest unknown

​Event reference

​Bounce categories

​The Email Detail Record (EDR)

​What produces an EDR — and what doesn’t

​Provisional and final records

​Lifecycle fields

​Error fields

​The 30xxx taxonomy

​error_evidence

​errors[]

​Webhook payloads

​Consuming the lifecycle

​Designing a consumer

​Delivery failures come in two layers

​Layer 1 — API errors (10xxx)

​Layer 2 — Delivery failures (30xxx)

​Related

The two-layer model

The lifecycle

Per-recipient states

The message-level track

What each recipient state means

How MTA callbacks map to events

Reception callbacks

System failures: stored, but not pushed

Complaints are additive, not a state change

Ambiguous injection: the honest unknown

Event reference

Bounce categories

The Email Detail Record (EDR)

What produces an EDR — and what doesn’t

Provisional and final records

Lifecycle fields

Error fields

The 30xxx taxonomy

`error_evidence`

`errors[]`

Webhook payloads

Consuming the lifecycle

Designing a consumer

Delivery failures come in two layers

Layer 1 — API errors (`10xxx`)

Layer 2 — Delivery failures (`30xxx`)

Related