Suppressions & Unsubscribes

Manage the Telnyx Email suppression list (blocklist) to protect your sender reputation. Suppressions stop Telnyx from sending to addresses that have bounced, complained, unsubscribed, or that you’ve manually blocked. This guide covers the suppression model, scope, CRUD operations, CSV import/export, send-time override behavior, unsubscribe groups, and the RFC 8058 one-click unsubscribe flow. All requests use the production base URL https://api.telnyx.com/v2 and an Authorization: Bearer *** header.

Suppression model

A suppression (block) is a record that prevents email from being sent to a recipient address. Telnyx creates suppressions automatically in response to deliverability signals, and you can create them manually via the API. Every suppression has a reason — the canonical enum string that describes why the block exists — and a source that records how it was created.

Reasons

Reason	Created by	Overridable with `ignore_suppression`?
`hard_bounce`	Auto — permanent bounce or soft-bounce escalation	No
`spam_complaint`	Auto — ARF feedback (complaint)	No
`invalid`	Import (SendGrid `invalid_emails`, generic) or internal	No
`unsubscribe`	Auto — recipient unsubscribed (RFC 8058 or link), or manual group opt-out	Yes
`manual_block`	Manual — public API `POST /email_blocks`, or CSV import (SendGrid `blocks`, generic `manual_block`)	Yes

The three non-overridable reasons (hard_bounce, spam_complaint, invalid) can never be bypassed by ignore_suppression — Telnyx will not deliver to those recipients regardless of the flag. The two overridable reasons (unsubscribe, manual_block) can be bypassed when you send with ignore_suppression: true and an API key that has the email:override scope. See Send-time behavior.

Sources

Source	Meaning
`system`	Auto-created by Telnyx (bounce, complaint, or unsubscribe workers)
`manual`	Created via the public API or group suppressions sub-resource
`import`	Created via CSV import
`feedback`	Created from feedback-loop data

How auto-suppressions are created

Telnyx’s delivery event pipeline classifies incoming KumoMTA log records and enqueues a suppression worker for suppressible events:

Spam complaint — an ARF Feedback record creates a spam_complaint suppression.
Hard bounce — a Bounce or OOB record with a 5.1.x or 5.2.x enhanced status code, or a 5xx SMTP code with no enhanced code, creates a hard_bounce suppression.
Soft-bounce escalation — repeated TransientFailure (deferred) records for the same recipient increment a counter; when the threshold is breached, Telnyx escalates to a hard_bounce suppression.
Expiration — a KumoMTA Expiration record (system gave up retrying) creates a hard_bounce suppression.
Unsubscribe — a recipient unsubscribes via the RFC 8058 one-click flow or the unsubscribe link, creating an unsubscribe suppression (see RFC 8058 one-click unsubscribe).

AdminBounce records, 5.7.x enhanced codes (sender-side policy), and other unclassified records are not suppressed.

The public API can only create manual_block suppressions. Any reason value you send to POST /email_blocks is ignored — the server forces reason: manual_block and source: manual. Auto-suppressions (hard_bounce, spam_complaint, unsubscribe) are created by Telnyx internally. CSV import is the one other path that can produce manual_block rows, with source: import.

Scope

A suppression’s scope determines which sends it blocks. Scope is derived server-side from the suppression’s domain_id and from fields — it’s never trusted from the client. There are exactly three scopes:

Scope	Condition	Blocks
`account`	`domain_id` is null	All sends to the recipient address, across all domains and senders. If `from` is also set, send-time matching still restricts the block to that sender.
`domain`	`domain_id` is set, `from` is null	Sends to the recipient from the specified domain
`address`	Both `domain_id` and `from` are set	Sends to the recipient from the specified sender address on the specified domain

At send time, Telnyx checks the recipient against all matching active suppressions. Account-scoped blocks match across all domains, but a non-null from still restricts matching to that sender. Domain-scoped blocks match when the send’s domain matches. Address-scoped blocks match when both domain and sender match.

`group_id` is a filter, not a scope

group_id is not a fourth scope — it’s an independent association that narrows which sends a suppression applies to, and it combines with whichever of the three scopes the record already has. A suppression with group_id: null applies to every send regardless of group; a suppression with group_id set applies only to sends that carry the same group_id. See Unsubscribe groups.

Manage suppressions

List suppressions

GET /email_blocks returns the account’s suppressions with offset or cursor pagination, sort, and filters.

curl

curl -X GET "https://api.telnyx.com/v2/email_blocks?page[number]=1&page[size]=25&filter[reason]=manual_block&sort=-created_at" \
  -H "Authorization: Bearer ***"

Parameter	Type	Notes
`page[number]`	int (≥1, default 1)	Offset pagination page number.
`page[size]`	int (1–100, default 25)	Page size for offset mode.
`page[after]`	string (cursor)	Cursor for forward pagination. Mutually exclusive with `page[number]` and `page[before]`.
`page[before]`	string (cursor)	Cursor for backward pagination.
`sort`	string	`created_at` (asc) or `-created_at` (desc, default). Only `created_at` is sortable.
`filter[reason]`	enum	`hard_bounce`, `spam_complaint`, `unsubscribe`, `invalid`, or `manual_block`.
`filter[domain_id]`	uuid	Filter by domain.
`filter[created_after]`	date-time	Suppressions created after this timestamp.
`filter[created_before]`	date-time	Suppressions created before this timestamp.

Offset-mode response (default):

{
  "data": [
    {
      "id": "5f3e2a1c-7b8d-4e2f-9a1c-3d5e7f9a1b2c",
      "record_type": "email_block",
      "domain_id": null,
      "group_id": null,
      "from": null,
      "to": "user@example.com",
      "reason": "manual_block",
      "source": "manual",
      "scope": "account",
      "status": "active",
      "created_at": "2026-07-06T12:00:00.000000Z",
      "updated_at": "2026-07-06T12:00:00.000000Z",
      "expires_at": null
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_results": 1
  }
}

Cursor-mode response (when you use page[after] or page[before]):

{
  "data": [
    {
      "id": "5f3e2a1c-7b8d-4e2f-9a1c-3d5e7f9a1b2c",
      "record_type": "email_block",
      "domain_id": null,
      "group_id": null,
      "from": null,
      "to": "user@example.com",
      "reason": "manual_block",
      "source": "manual",
      "scope": "account",
      "status": "active",
      "created_at": "2026-07-06T12:00:00.000000Z",
      "updated_at": "2026-07-06T12:00:00.000000Z",
      "expires_at": null
    }
  ],
  "meta": {
    "page_size": 25,
    "next_cursor": "eyJjcm...Ijoi...",
    "previous_cursor": "eyJjcm...Ijoy...",
    "has_next": true,
    "has_previous": true
  }
}

Cursor meta always carries page_size, next_cursor, previous_cursor, has_next, and has_previous. All five keys are always present in the response; when there is no next or previous page, the corresponding cursor is null (not omitted).

Retrieve a suppression

GET /email_blocks/{id} returns a single suppression by ID.

curl

curl -X GET https://api.telnyx.com/v2/email_blocks/5f3e2a1c-7b8d-4e2f-9a1c-3d5e7f9a1b2c \
  -H "Authorization: Bearer ***"

Returns 200 with the suppression in data, or 404 if the ID doesn’t exist or belongs to another account.

Create a manual suppression

POST /email_blocks creates a manual_block suppression. The server forces reason: manual_block and source: manual regardless of any values you send.

curl

curl -X POST https://api.telnyx.com/v2/email_blocks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "to": "spammer@bad.tld",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Field	Type	Notes
`to`	string (required)	The recipient address. Normalized to lowercase, trimmed.
`from`	string	Sender address. When null, the suppression is account- or domain-scoped.
`domain_id`	uuid	When null, the suppression is account-scoped.
`expires_at`	date-time	Stored as metadata on the suppression. Not currently enforced — see the note below.

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "record_type": "email_block",
    "domain_id": null,
    "group_id": null,
    "from": null,
    "to": "spammer@bad.tld",
    "reason": "manual_block",
    "source": "manual",
    "scope": "account",
    "status": "active",
    "created_at": "2026-07-06T12:30:00.000000Z",
    "updated_at": "2026-07-06T12:30:00.000000Z",
    "expires_at": "2026-12-31T23:59:59Z"
  }
}

expires_at is not currently enforced. The field is accepted, stored, and returned, but no expiration process runs against it: the send-time suppression check matches on status = "active" alone and never compares expires_at to the current time. A suppression with a past expires_at keeps blocking sends. Treat expires_at as informational metadata and remove suppressions explicitly with DELETE /email_blocks/{id} when you want them to stop applying.

Creating a suppression that already exists and is still active (same account, scope, recipient, reason, domain, from, and group) is idempotent — the API returns 200 with the existing record and creates no new audit event. If the matching record was previously removed, the create reactivates it instead: the existing row flips back to status: "active", the request’s expires_at is re-applied, a fresh created audit event is appended, and the API returns 201. The row is reused rather than duplicated, so the audit trail reads created → removed → created on the same suppression ID.

Existing record	Response	Audit event
None	`201 Created`	`created`
Active duplicate	`200 OK`	none
Previously removed	`201 Created` (reactivated)	`created`

Delete a suppression

DELETE /email_blocks/{id} soft-deletes a suppression. The record is retained with status: "removed" and a removed audit event is appended.

curl

curl -X DELETE https://api.telnyx.com/v2/email_blocks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ***"

Returns 200 with the suppression (now status: "removed"). Deleting an already-removed suppression is idempotent — returns 200 with no new event.

Suppression audit events

GET /email_blocks/{id}/events lists the audit trail for a suppression. Each event records a lifecycle transition.

curl

curl -X GET "https://api.telnyx.com/v2/email_blocks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/events?page[size]=50" \
  -H "Authorization: Bearer ***"

{
  "data": [
    {
      "id": "e1...",
      "record_type": "email_block_event",
      "event_type": "created",
      "reason": "manual_block",
      "source": "manual",
      "actor": "user-123",
      "meta": {},
      "occurred_at": "2026-07-06T12:30:00.000000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 50,
    "total_pages": 1,
    "total_results": 1
  }
}

`event_type`	When
`created`	The suppression was created, or a previously removed suppression was reactivated by a new create.
`removed`	The suppression was deleted.
`expired`	Reserved. No process currently emits this event — `expires_at` is not enforced, so suppressions do not transition to `expired` on their own.
`override_used`	A send bypassed this suppression via `ignore_suppression` (overridable reasons only).

Uses offset pagination (page[number] default 1, page[size] default 50, max 100). Events are ordered by occurred_at descending.

CSV import & export

Migrate an existing suppression list from SendGrid, Mailgun, or Amazon SES, or import a generic CSV. Export your Telnyx suppressions as CSV for backup or transfer.

Import a CSV

POST /email_blocks/import accepts a multipart upload with a CSV file and returns 202 with an async import job. The provider format is auto-detected from the CSV header row.

curl

curl -X POST https://api.telnyx.com/v2/email_blocks/import \
  -H "Authorization: Bearer ***" \
  -F "file=@blocks.csv" \
  -F "block_ttl_days=30"

Form field	Type	Notes
`file`	binary (required)	The CSV file.
`block_ttl_days`	int (default 30)	TTL applied to imported `manual_block` rows only. All other reasons get indefinite (`expires_at: null`). Invalid or missing falls back to 30.

Limits: decoded CSV up to 25 MiB and 250,000 data rows. Exceeding either returns 413. All imported suppressions are account-scoped (scope: account, domain_id: null, from: null).

Provider auto-detection

The importer detects the provider from the CSV header row (normalized to lowercase, trimmed):

Provider	Detected by	Reason mapping
SendGrid	Header has `email` + `type`	`blocks`→`manual_block`, `bounces`→`hard_bounce`, `spam_reports`→`spam_complaint`, `unsubscribes`→`unsubscribe`, `invalid_emails`→`invalid`
Mailgun	Header has `recipient`	`bounces`→`hard_bounce`, `complains`→`spam_complaint`, `unsubscribes`→`unsubscribe`
Amazon SES	Header has `email` + (`bounce_type` or `complaint_type` or `diagnostic`)	Non-blank `bounce_type`→`hard_bounce`, non-blank `complaint_type`→`spam_complaint`
Generic	Header has `email`, `to`, or `to_address`	`reason` column must be one of: `hard_bounce`, `spam_complaint`, `unsubscribe`, `invalid`, `manual_block`

Detection order is SendGrid → Mailgun → SES → generic. An undetectable or header-only CSV returns 400. Rows with a missing or blank email address, or an unmappable reason, are skipped and recorded in the import’s errors map (keyed by row number, 1-indexed with the header as row 1).

Poll an import job

GET /email_blocks/import/{id} returns the current state of an import job. Poll this until status is completed or failed.

curl

curl -X GET https://api.telnyx.com/v2/email_blocks/import/2c3d4e5f-... \
  -H "Authorization: Bearer ***"

{
  "data": {
    "id": "2c3d4e5f-...",
    "record_type": "email_block_import",
    "status": "completed",
    "total": 2,
    "provider": "sendgrid",
    "created_at": "2026-07-06T13:00:00.000000Z",
    "updated_at": "2026-07-06T13:00:05.000000Z",
    "completed_at": "2026-07-06T13:00:05.00Z",
    "processed_rows": 2,
    "created_count": 2,
    "existing_count": 0,
    "skipped_count": 0,
    "error_count": 0
  }
}

`status`	Meaning
`pending`	Job enqueued, not yet started.
`processing`	Worker is importing rows.
`completed`	Import finished. Counts and `completed_at` are present.
`failed`	Import failed. `failure_reason` is present.

When status is completed, the response includes processed_rows, created_count, existing_count, skipped_count, and error_count. Rejected rows are counted in skipped_count and detailed in an errors object that maps row numbers to skip reasons. error_count tracks a separate failure class that the importer does not currently populate, so it stays 0 even when rows were rejected:

{
  "data": {
    "id": "...",
    "status": "completed",
    "total": 3,
    "provider": "generic",
    "processed_rows": 3,
    "created_count": 2,
    "existing_count": 0,
    "skipped_count": 1,
    "error_count": 0,
    "errors": {
      "3": "unmapped reason: deferred"
    }
  }
}

Use skipped_count and errors — not error_count — to detect rows the importer rejected. A row with a missing/blank email address or an unmappable reason increments skipped_count and gets an entry in errors; error_count remains 0.

Also note block_ttl_days only writes an expires_at value onto imported manual_block rows; because expires_at is not enforced, those rows keep blocking after the TTL date passes until you delete them.

Export suppressions as CSV

GET /email_blocks/export streams the account’s suppressions as a chunked CSV response with Content-Type: text/csv. Filters affect which rows are exported; sort and page parameters are accepted but ignored.

curl

curl -X GET "https://api.telnyx.com/v2/email_blocks/export?filter[reason]=manual_block" \
  -H "Authorization: Bearer ***" \
  -H "Accept: text/csv" \
  -o email_blocks_export.csv

The CSV columns, in order: id,to,from,reason,source,scope,status,domain_id,created_at,updated_at,expires_at,group_id.

id,to,from,reason,source,scope,status,domain_id,created_at,updated_at,expires_at,group_id
a1b2c3d4-e5f6-7890-abcd-ef1234567890,spammer@bad.tld,,manual_block,manual,account,active,,2026-07-06T12:30:00.000000Z,2026-07-06T12:30:00.000000Z,2026-12-31T23:59:59Z,

Export → import is lossy — it is not a round-trip. The export writes all twelve columns, but the generic importer only consumes to/to_address/email and reason. Everything else in the file is discarded: from, domain_id, group_id, source, status, id, and the exported expires_at are all dropped on re-import.Consequences of re-importing your own export:

Domain- and address-scoped suppressions are broadened to account scope. Every imported row is written with from_address: null, domain_id: null, scope: account, so a block that previously applied to one sending domain now blocks that recipient across your whole account.
Group-scoped opt-outs become global. group_id is not read on import, so a newsletter-only unsubscribe re-imports as a suppression that blocks every send to that recipient, including transactional mail.
Expiry metadata is not preserved. Imported manual_block rows get a fresh expires_at derived from block_ttl_days; every other reason gets expires_at: null.
Removed rows come back active. status is ignored, so an exported tombstone re-imports as an active suppression.

Use the export for backup, reporting, or migration to another system — not as a way to restore Telnyx state. To recreate scoped or group-scoped suppressions faithfully, replay them through POST /email_blocks (with domain_id / from) or POST /email_unsubscribe_groups/{id}/suppressions.

Send-time behavior

When you send an email, Telnyx checks every recipient against the suppression list before creating the message. Suppressed recipients are reported in the response — they’re never silently dropped.

Partial suppression (202)

When some recipients are suppressed but others are not, the send proceeds for the non-suppressed recipients. The 202 response includes a top-level suppressed array describing each suppressed recipient:

{
  "data": {
    "record_type": "email_message",
    "id": "...",
    "status": "queued"
  },
  "suppressed": [
    {
      "to": "suppressed@example.com",
      "reason": "hard_bounce",
      "scope": "account",
      "override_allowed": false
    }
  ]
}

Each entry in the suppressed array has:

Field	Type	Notes
`to`	string	The suppressed recipient address.
`reason`	string	The suppression reason (e.g. `hard_bounce`).
`scope`	string	The scope that matched (e.g. `account`, `domain`, `address`).
`override_allowed`	boolean	`true` if the suppression is overridable (`unsubscribe`, `manual_block`); `false` if non-overridable (`hard_bounce`, `spam_complaint`, `invalid`).

All recipients suppressed (422)

When every recipient is suppressed, the request returns 422 with a recipient_suppressed error code and the suppressed array:

{
  "errors": [
    {
      "code": "recipient_suppressed",
      "title": "Recipient Suppressed",
      "detail": "All recipients are suppressed. The email was not sent."
    }
  ],
  "suppressed": [
    {
      "to": "suppressed@example.com",
      "reason": "hard_bounce",
      "scope": "account",
      "override_allowed": false
    }
  ]
}

Batch sends

In a batch (POST /email_messages/batch), suppression is checked per message. A message whose recipients are all suppressed produces a per-item error with code: "recipient_suppressed" in the batch response’s errors array (indexed by position in the request).

Overriding suppressions

Set ignore_suppression: true on a send to bypass overridable suppressions (unsubscribe and manual_block). This requires an API key with the email:override scope — without it, the request returns 403:

{
  "errors": [
    {
      "code": "10007",
      "title": "Forbidden",
      "detail": "This action requires the email:override scope"
    }
  ]
}

When ignore_suppression: true is honored:

Recipients with only overridable suppressions (override_allowed: true) proceed — the send goes through and an override_used audit event is recorded on each bypassed suppression.
Recipients with any non-overridable suppression (override_allowed: false) remain blocked — ignore_suppression cannot bypass hard_bounce, spam_complaint, or invalid.

The scope hierarchy grants email:override to keys with full_access or email:admin. Keys with only email:send or email:read cannot override.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "from": "sender@example.com",
    "to": ["unsubscribed@example.com", "new@example.com"],
    "subject": "Transactional update",
    "text_body": "Your account was updated.",
    "ignore_suppression": true
  }'

ignore_suppression can only bypass unsubscribe and manual_block. It will never override a hard_bounce, spam_complaint, or invalid suppression — those recipients stay blocked and appear in the suppressed array even when the flag is set.

Unsubscribe groups

Unsubscribe groups let you suppress a recipient for one category of email without blocking all your sends to them. This is the standard pattern for separating newsletter opt-outs from transactional email. For example, a recipient who unsubscribes from your “Weekly Newsletter” group should still receive password-reset emails. Group-scoped suppressions only block sends that specify the same group_id.

Create a group

POST /email_unsubscribe_groups creates a group.

curl

curl -X POST https://api.telnyx.com/v2/email_unsubscribe_groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "name": "Newsletter",
    "description": "Weekly digest"
  }'

Field	Type	Notes
`name`	string (required, 1–255)	Group name.
`description`	string	Optional description.

{
  "data": {
    "id": "g2...",
    "record_type": "email_unsubscribe_group",
    "name": "Newsletter",
    "description": "Weekly digest",
    "created_at": "2026-07-06T14:00:00.000000Z",
    "updated_at": "2026-07-06T14:00:00.000000Z"
  }
}

List, retrieve, update, and delete groups

GET /email_unsubscribe_groups — list groups (offset pagination, page[size] default 25, max 100).
GET /email_unsubscribe_groups/{id} — retrieve a group.
PATCH /email_unsubscribe_groups/{id} — update name and/or description. PUT is not supported.
DELETE /email_unsubscribe_groups/{id} — delete a group. If the group has active suppressions, the request returns 409 unless you pass ?force=true, which soft-deletes the suppressions first.

Manage suppressions in a group

GET /email_unsubscribe_groups/{id}/suppressions — list suppressions in a group (offset pagination).
POST /email_unsubscribe_groups/{id}/suppressions — add a recipient to the group’s suppression list. The server forces reason: unsubscribe, source: manual, and group_id: <this group>. Only to is read from the request body.
DELETE /email_unsubscribe_groups/{id}/suppressions/{email} — remove a recipient from the group’s suppression list. Returns 204.

curl

curl -X POST https://api.telnyx.com/v2/email_unsubscribe_groups/g2.../suppressions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{ "to": "opted.out@example.com" }'

Send with a group

Pass group_id on a send to scope the suppression check to that group. The send will check account-, domain-, and address-scoped suppressions as usual. Records with group_id: null apply to every send regardless of group; records with group_id set additionally require the same group_id to match.

curl

curl -X POST https://api.telnyx.com/v2/email_messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "from": "news@example.com",
    "to": ["subscriber@example.com"],
    "subject": "This week's updates",
    "text_body": "Here's what happened this week.",
    "group_id": "g2..."
  }'

The group_id you set on a send is persisted on the message. When the recipient later unsubscribes via the RFC 8058 one-click flow, the resulting suppression is scoped to that same group — so the opt-out only affects future sends to that group, not your transactional email.

RFC 8058 one-click unsubscribe

RFC 8058 defines a one-click unsubscribe mechanism: supporting email clients (Gmail, Yahoo, Apple Mail, and others) send an automatic POST to a unsubscribe URL when the recipient clicks the unsubscribe button, without the recipient having to visit a web page.

How it works

Headers on outgoing mail. When the sending domain has unsubscribe_tracking enabled (the default), Telnyx adds two headers to every outgoing message:
- List-Unsubscribe: <https://...tracking/unsubscribe/{token}> — a signed, unguessable URL.
- List-Unsubscribe-Post: List-Unsubscribe=One-Click — signals RFC 8058 support to the mailbox provider.
Recipient unsubscribes. A recipient can unsubscribe two ways:
- One-click (POST) — the email client sends an automatic POST to the unsubscribe URL (RFC 8058). Telnyx records the unsubscribe with method: "one_click".
- Link (GET) — the recipient clicks the unsubscribe link and lands on a confirmation page. Telnyx records the unsubscribe with method: "link".
Suppression created. Telnyx enqueues a worker that creates an unsubscribe suppression for the recipient. When the original send specified a group_id, the suppression is scoped to that group.
Event recorded. Telnyx records an email.unsubscribed event on the message (with the method — link or one_click). These events also flow to configured webhooks.

Both POST and GET always return 200, even for invalid tokens, to avoid leaking information about which message IDs exist (per RFC 8058 §3).

Enabled by default

unsubscribe_tracking defaults to true for every email domain. This is intentional: Gmail and Yahoo require RFC 8058 one-click unsubscribe support for bulk senders. You can disable it per domain if you handle unsubscribes yourself, but doing so risks deliverability problems with those providers.

curl

curl -X PATCH https://api.telnyx.com/v2/email_domains/{domain_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "tracking": {
      "unsubscribe_tracking": true,
      "open_tracking": false,
      "click_tracking": false
    }
  }'

Open and click tracking default to false; unsubscribe tracking defaults to true. The one-click unsubscribe flow only fires when the sending domain has unsubscribe_tracking enabled.

The List-Unsubscribe URL carries a signed HMAC token, not a bare message ID. If the signing key is missing or misconfigured, Telnyx omits the unsubscribe headers entirely rather than emitting an invalid token — recipients can’t unsubscribe from a message with no headers, but they also won’t see a broken unsubscribe button.

Getting Started

Domains & DNS

Sending Email

Receiving Email

Email Validations

Templates

Events & Webhooks

Suppressions

Deliverability

Suppressions & Unsubscribes

Suppression model

Reasons

Sources

How auto-suppressions are created

Scope

`group_id` is a filter, not a scope

Manage suppressions

List suppressions

Retrieve a suppression

Create a manual suppression

Delete a suppression

Suppression audit events

CSV import & export

Import a CSV

Provider auto-detection

Poll an import job

Export suppressions as CSV

Send-time behavior

Partial suppression (202)

All recipients suppressed (422)

Batch sends

Overriding suppressions

Unsubscribe groups

Create a group

List, retrieve, update, and delete groups

Manage suppressions in a group

Send with a group

RFC 8058 one-click unsubscribe

How it works

Enabled by default

​Suppression model

​Reasons

​Sources

​How auto-suppressions are created

​Scope

​group_id is a filter, not a scope

​Manage suppressions

​List suppressions

​Retrieve a suppression

​Create a manual suppression

​Delete a suppression

​Suppression audit events

​CSV import & export

​Import a CSV

​Provider auto-detection

​Poll an import job

​Export suppressions as CSV

​Send-time behavior

​Partial suppression (202)

​All recipients suppressed (422)

​Batch sends

​Overriding suppressions

​Unsubscribe groups

​Create a group

​List, retrieve, update, and delete groups

​Manage suppressions in a group

​Send with a group

​RFC 8058 one-click unsubscribe

​How it works

​Enabled by default

Suppression model

Reasons

Sources

How auto-suppressions are created

Scope

`group_id` is a filter, not a scope

Manage suppressions

List suppressions

Retrieve a suppression

Create a manual suppression

Delete a suppression

Suppression audit events

CSV import & export

Import a CSV

Provider auto-detection

Poll an import job

Export suppressions as CSV

Send-time behavior

Partial suppression (202)

All recipients suppressed (422)

Batch sends

Overriding suppressions

Unsubscribe groups

Create a group

List, retrieve, update, and delete groups

Manage suppressions in a group

Send with a group

RFC 8058 one-click unsubscribe

How it works

Enabled by default