/telnyx-email-suppressions-curl

name: telnyx-email-suppressions-curl
description: >-
  Manage email suppressions (blocks), import and export suppression lists,
  and manage unsubscribe groups. Use for deliverability compliance and
  bounce handling.
metadata:
  author: telnyx
  product: email
  language: curl

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Email Suppressions - curl

Installation

# curl is pre-installed on macOS, Linux, and Windows 10+
# jq is required for the import polling examples below:
#   macOS: brew install jq
#   Debian/Ubuntu: sudo apt-get install jq

Setup

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use `$TELNYX_API_KEY` for authentication and the API base URL `https://api.telnyx.com/v2`.

Error Handling

All API calls can fail with network errors, authentication errors (401), or framework errors (406). List-query validation failures return 400, resource lookups can return 404, and JSON body validation failures normally return 422. Inspect the HTTP status and the top-level `.errors` array before continuing:

response_file=$(mktemp)
status=$(curl --silent --show-error \
  --output "$response_file" \
  --write-out '%{http_code}' \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/email_blocks")

if [ "$status" -lt 200 ] || [ "$status" -ge 300 ]; then
  printf 'Telnyx API error (HTTP %s):\n' "$status" >&2
  jq . "$response_file" >&2
  rm -f "$response_file"
  exit 1
fi
jq . "$response_file"
rm -f "$response_file"

Common statuses are `400` malformed query or import, `401` invalid API key, `404` resource not found, `409` group still has active suppressions, `413` import too large, and `422` invalid request attributes. A successful delete may return `204 No Content`; do not attempt to parse that response as JSON.

Important Notes

• **Account isolation:** Every lookup is scoped to the authenticated account. A malformed UUID or a UUID owned by another account is reported as 404.
• **Normalized addresses:** Recipient addresses are trimmed and lower-cased. The `from` address on a manual block is also normalized.
• **Pagination:** Most list operations use `page[number]` and `page[size]` (maximum 100). The main block list also supports opaque cursors. Do not combine offset and cursor modes.
• **URL encoding:** Percent-encode an email address placed in a URL path. For example, use `alice%40example.com`, not an untrusted raw string.
• **Idempotency:** Creating a block or adding a group suppression returns 200 when the matching suppression already exists and 201 when a row is created.

Operational Caveats

• `POST /v2/email_blocks` always creates `reason: manual_block` with `source: manual`. Customers cannot use this endpoint to create `hard_bounce`, `spam_complaint`, or `invalid` suppressions; caller-supplied `reason` and `source` are ignored.
• Scope is server-derived as `account`, `domain`, or `address`, never customer-set: no `domain_id` and no `from` gives `account`; `domain_id` without `from` gives `domain`; a `from` address gives `address` scope.
• `unsubscribe` and `manual_block` are overridable at send time with `ignore_suppression: true`. `hard_bounce`, `spam_complaint`, and `invalid` are not overridable. Bypassing an overridable suppression should be deliberate and auditable.
• Import is asynchronous. `POST /v2/email_blocks/import` returns 202 and a job ID; poll `GET /v2/email_blocks/import/{id}` until `completed` or `failed`. Import behavior for scoped suppressions may vary. Check the import result for the actual scope assigned.
• Export is synchronous and streams CSV directly. It does not create a job.
• Deleting a block is a soft delete: the row remains as a tombstone with `status: removed`. Recreating the same removed suppression reactivates it.
• The `expires_at` field is available for setting an expiration timestamp on suppressions.
• Check both `error_count` and `skipped_count` in the import response for rejected entries.
• A group suppression prevents sending to that address for every campaign that uses the unsubscribe group. It is not an account-wide unsubscribe for campaigns that do not use that group.

Reference Use Rules

Do not invent Telnyx parameters, enums, response fields, import counters, or CSV columns.

• Read [references/api-details.md](references/api-details.md) before building pagination, bulk migration, or delete automation.
• Before deciding whether a send may bypass a block, read [suppression semantics](references/api-details.md#suppression-semantics).
• Before importing an exported list, read [CSV export and import](references/api-details.md#csv-export-and-import) and verify the scope assigned by the import result.
• For exhaustive request fields, response fields, status codes, and operation IDs, use [the operation catalog](references/api-details.md#operation-catalog) and [response schemas](references/api-details.md#response-schemas).

Core Tasks

List suppressions

Use offset pagination for page-oriented tools or cursor pagination for sequential traversal without page-number offsets.

`GET /v2/email_blocks`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page[number]` | integer | No | Offset page, default 1. Do not combine with a cursor. | | `page[size]` | integer | No | 1-100, default 25. | | `page[after]` | string | No | Opaque next-page cursor. Exclusive with `page[number]` and `page[before]`. | | `page[before]` | string | No | Opaque previous-page cursor. Exclusive with `page[number]` and `page[after]`. | | `sort` | enum | No | `created_at` or `-created_at` (default). | | `filter[reason]` | enum | No | Exact reason match. | | `filter[domain_id]` | UUID | No | Exact domain ID match. | | `filter[created_after]` | date-time | No | Match `created_at > value`. | | `filter[created_before]` | date-time | No | Match `created_at < value`. |

curl --get --silent --show-error \