List account 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.
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
// Automatically fetches more pages as needed.
for await (const response of client.emailEvents.list()) {
console.log(response);
}import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
page = client.email_events.list()
print(page.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
emailEvents, err := client.EmailEvents.List(context.TODO())
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", emailEvents.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
var page = client.emailEvents().list();
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
page = telnyx.email_events.list
puts(page)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$page = $client->emailEvents->list();
var_dump($page);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx email-events list \
--api-key 'My API Key'curl --request GET \
--url https://api.telnyx.com/v2/email_events \
--header 'Authorization: Bearer <token>'{
"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": "[email protected]",
"name": "Telnyx"
},
"to": {
"email": "[email protected]",
"name": null,
"kind": "to"
},
"subject": "Welcome"
}
}
],
"meta": {
"page_size": 50,
"time_range": {
"from": "2026-07-01T00:00:00Z",
"to": "2026-07-31T00:00:00Z"
}
}
}{
"errors": [
{
"code": "10006",
"title": "Not authorized",
"detail": "Invalid API key",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10006"
}
}
]
}Authorizations
Telnyx API key supplied as Authorization: Bearer <token>. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.
Query Parameters
Number of results to return. Defaults to 25; maximum is 100. Invalid values are clamped to the valid range.
1 <= x <= 100Opaque URL-safe Base64 cursor returned by a previous event list response. The legacy page[after] and flat page_cursor forms are also accepted.
Comma-separated list of event types to include. Also accepts repeated query parameters (e.g. event_type=delivered&event_type=bounced). Unknown values return no matches.
Dual-name compatibility: values are accepted
bare or email.-prefixed. A legacy value keeps matching the
rows it matched pre-rename — no widening: failed also
matches the rows that now store the canonical names of the
outcomes it covered (gw_reject, injection_timeout,
expired); bounced matches stored bounced rows only
(recipient-scoped Expirations stored failed pre-rename and
never matched bounced, so expired is deliberately not a
bounced expansion). A canonical value matches its own rows
plus legacy rows whose recorded payload evidence proves that
outcome (expired also surfaces legacy bounced rows with
bounce_category: transient). The additive
canonical_event_type field in each response row names the
canonical outcome.
Filter events for a specific email message UUID. Invalid UUID values are silently ignored (no filter applied).
Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when omitted.
Inclusive ISO 8601 end timestamp. When from is provided without to, defaults to from + 30 days.
Was this page helpful?
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
// Automatically fetches more pages as needed.
for await (const response of client.emailEvents.list()) {
console.log(response);
}import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
page = client.email_events.list()
print(page.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
emailEvents, err := client.EmailEvents.List(context.TODO())
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", emailEvents.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
var page = client.emailEvents().list();
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
page = telnyx.email_events.list
puts(page)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$page = $client->emailEvents->list();
var_dump($page);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx email-events list \
--api-key 'My API Key'curl --request GET \
--url https://api.telnyx.com/v2/email_events \
--header 'Authorization: Bearer <token>'{
"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": "[email protected]",
"name": "Telnyx"
},
"to": {
"email": "[email protected]",
"name": null,
"kind": "to"
},
"subject": "Welcome"
}
}
],
"meta": {
"page_size": 50,
"time_range": {
"from": "2026-07-01T00:00:00Z",
"to": "2026-07-31T00:00:00Z"
}
}
}{
"errors": [
{
"code": "10006",
"title": "Not authorized",
"detail": "Invalid API key",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10006"
}
}
]
}