---
title: "List account email events"
method: GET
path: "/email_events"
tags: ["Email Events"]
---

# List account email events

`GET /email_events`

Lists account-level email events sorted oldest first by `occurred_at asc, id asc`. Each row contains a legacy email.-prefixed event_type and an additive canonical_event_type. Gateway rejection renders email.failed with canonical email.gw_reject; ambiguous injection timeout renders email.injection_timeout in both; MTA expiration renders email.bounced with canonical email.expired. Message-scoped queued, sending, sandbox, cancelled, and daily_limit_exceeded rows fan out per durable recipient with stable derived IDs matching webhook delivery. Scheduled is the cardinality exception: account polling retains one message-scoped scheduled row with its stored event ID, while scheduled webhook publication fans out per recipient with derived IDs; reconcile scheduled events by message ID, event type, and occurrence time rather than event UUID. Recipient-scoped stored rows retain their stored UUIDs across polling and webhook delivery. Legacy names are derived from stored rows; an AdminBounce row stored as failed renders email.failed in polling while its webhook retains email.bounced, both with canonical email.failed.

## Query parameters

- `page_size` integer
- `page[cursor]` string
- `event_type` union
  - string
  - string[]
- `email_id` string, uuid
- `from` string, date-time
- `to` string, date-time

## Response `200`

Paginated list of account email events.

- AccountEmailEventListResponse
  - `data` AccountEmailEvent[], required
    - `id` string, uuid, required — Event UUID.
    - `event_type` string, required — Legacy customer-visible event name, prefixed with `email.`. Gateway rejections render `email.failed`; MTA expirations render `email.bounced`. Webhook subscription allowlists match the legacy name.
    - `canonical_event_type` string, required — Additive canonical outcome name, prefixed with `email.`. Gateway rejection is `email.gw_reject`, ambiguous injection timeout is `email.injection_timeout`, and MTA expiration is `email.expired`. Unchanged outcomes retain their names. Existing stored rows are translated only when recorded payload evidence proves the outcome; a legacy failed row is not guessed or sharpened.
    - `occurred_at` string, date-time, required
    - `recipient_id` string, uuid — Durable email recipient UUID. Present for recipient-scoped events, including each queued, sending, sandbox, cancelled, and daily_limit_exceeded fan-out event.
    - `payload` AccountEmailEventPayload, required — Payload returned by GET /email_events. Every row includes id, status, and occurred_at. Recipient-scoped rows also include recipient_id, from, subject, and exactly one object-valued to, cc, or bcc field. Legacy or message-scoped rows can omit recipient_id and use object-valued or string-valued to/cc fields, including an empty string when no address exists; bcc is redacted. If the related message or recipient cannot be loaded, the minimal fallback can omit from, subject, and recipient fields. Additional persisted public evidence can be present.
      - `id` string, uuid, required — Email message UUID.
      - `recipient_id` string, uuid — Durable email recipient UUID. Present for recipient-scoped events.
      - `status` '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' | 'expired', required — Stored event outcome slug, not the authoritative recipient status. Account polling returns the stored name, including suppression, scan, and quarantine lifecycle names. Webhooks retain legacy payload names: gateway rejections use failed and MTA expirations use bounced. New sharp stored rows can expose gw_reject, injection_timeout, or expired. Use the envelope canonical_event_type to identify the outcome across surfaces.
      - `occurred_at` string, date-time, required
      - `from` AccountEmailEventSender — Sender projection in account event polling. The display name is explicitly null when the message has no sender name.
        - `email` string, email, required
        - `name` string, nullable, required
      - `to` union
        - EmailWebhookRecipient
          - `email` string, email, required
          - `name` string, nullable
          - `kind` 'to' | 'cc' | 'bcc'
        - string — Legacy message-scoped address, or an empty string when absent.
      - `cc` union
        - EmailWebhookRecipient
          - `email` string, email, required
          - `name` string, nullable
          - `kind` 'to' | 'cc' | 'bcc'
        - string — Legacy message-scoped address, or an empty string when absent.
      - `bcc` union
        - EmailWebhookRecipient
          - `email` string, email, required
          - `name` string, nullable
          - `kind` 'to' | 'cc' | 'bcc'
        - 'redacted'
      - `subject` string
  - `meta` EventPaginationMeta, required
    - `page_size` integer, required
    - `time_range` TimeRange, required
      - `from` string, date-time, nullable, required
      - `to` string, date-time, nullable, required
    - `page_cursor` string — Cursor for the next page, when more results are available.

## Other responses

- `401` — Not authorized (10006).

## Changes

> 99 revisions in range; 1 not diffed.

- **2026-09-23** `16bfa298dc71` — 3 breaking, 2 warning, 14 info
  - removed the required property `data/items/email_id` from the response with the `200` status
  - removed the required property `data/items/record_type` from the response with the `200` status
  - removed the required property `data/items/type` from the response with the `200` status
  - deleted the `query` request parameter `page_cursor`
  - …15 more
- **2026-09-22** `9621f6123ebc` — 2 warning
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `401`
  - added the new `domain_graduation_limit_exceeded` enum value to the `errors/items/code` response property for the response status `401`
- **2026-07-28** `b1bf96d8391e` — 1 warning
  - added the new `daily_limit_exceeded` enum value to the `data/items/type` response property for the response status `200`
- **2026-07-16** `2fb3b617430a` — 2 warning, 1 info
  - added the new `recipient_suppressed` enum value to the `errors/items/code` response property for the response status `401`
  - added the new `reputation_suspended` enum value to the `errors/items/code` response property for the response status `401`
  - added the optional property `suppressed` to the response with the `401` status
- …earlier changes not shown

[Full history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/email_events/get.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/227c33b1ac9c?raw)