telnyx-email-suppressions-curl
Manage email suppressions (blocks), import and export suppression lists, and manage unsubscribe groups. Use for deliverability compliance and bounce handling.
team-telnyx · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add team-telnyx/ai --skill 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
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
fromaddress on a manual block is also normalized. - Pagination: Most list operations use
page[number]andpage[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_blocksalways createsreason: manual_blockwithsource: manual. Customers cannot use this endpoint to createhard_bounce,spam_complaint, orinvalidsuppressions; caller-suppliedreasonandsourceare ignored.- Scope is server-derived as
account,domain, oraddress, never customer-set: nodomain_idand nofromgivesaccount;domain_idwithoutfromgivesdomain; afromaddress givesaddressscope. unsubscribeandmanual_blockare overridable at send time withignore_suppression: true.hard_bounce,spam_complaint, andinvalidare not overridable. Bypassing an overridable suppression should be deliberate and auditable.- Import is asynchronous.
POST /v2/email_blocks/importreturns 202 and a job ID; pollGET /v2/email_blocks/import/{id}untilcompletedorfailed. 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_atfield is available for setting an expiration timestamp on suppressions. - Check both
error_countandskipped_countin 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 before building pagination, bulk migration, or delete automation.
- Before deciding whether a send may bypass a block, read suppression semantics.
- Before importing an exported list, read 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 and 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 \
阅读完整来源 ↗