telnyx-email-inbound-curl
Manage email inboxes, list and search inbound messages, threads, sender filters, and reply to or forward messages. Use for building email agents that read and respond to incoming email.
team-telnyx · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add team-telnyx/ai --skill telnyx-email-inbound-curl技能说明
name: telnyx-email-inbound-curl description: >- Manage email inboxes, list and search inbound messages, threads, sender filters, and reply to or forward messages. Use for building email agents that read and respond to incoming email. metadata: author: telnyx product: email language: curl
Telnyx Email Inbound - curl
Installation
# curl is pre-installed on macOS, Linux, and Windows 10+
Setup
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
export TELNYX_API_BASE="https://api.telnyx.com/v2"
All examples below use $TELNYX_API_KEY for authentication. Resource IDs are UUIDs;
store the IDs returned by create and list calls rather than parsing them from email
addresses.
Error Handling
All API calls can fail with network errors, authentication errors (401), validation errors (422), temporary service errors (503), or rate limits (429). Capture the HTTP status separately from the JSON response in production:
response_file="$(mktemp)"
status="$({ curl -sS \
-o "$response_file" \
-w '%{http_code}' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"$TELNYX_API_BASE/email_inboxes"; } || printf '000')"
if [[ "$status" != "200" ]]; then
printf 'Telnyx request failed (HTTP %s)\n' "$status" >&2
jq . "$response_file" >&2 2>/dev/null || true
fi
rm -f "$response_file"
Common status codes:
| Status | Meaning | Action |
|---|---|---|
400 | Malformed request or send-time prerequisite failure | Fix the request; do not retry unchanged. |
401 | Invalid or missing API key | Replace the key and retry. |
403 | The account or inbox domain cannot send | Correct permissions or sending-domain configuration. |
404 | Resource is missing, deleted, foreign, or the sending domain could not be resolved | Re-list account-scoped resources; do not use the response to infer foreign resource existence. |
422 | Validation failed or every action recipient was suppressed | Read .errors[] and fix the referenced field. |
429 | Rate limited or inbox-domain reputation suspended sending | Honor retry guidance for rate limits; reputation suspension requires remediation. |
503 | Inbound storage, actions, or a dependency is unavailable | Retry with bounded exponential backoff and jitter. |
Important Notes
- Base path: The OpenAPI path names are relative to
https://api.telnyx.com/v2. - Authentication: Send
Authorization: Bearer $TELNYX_API_KEYon every request. - Identifiers:
inbox_id,message_id, andthread_idpath parameters are Telnyx UUIDs. A message's RFCMessage-IDappears separately as themessage_idresponse field. - Pagination: Inbox listing uses
page_sizeandpage_cursor. Message and thread listing usespage[size]andpage[after]. Continue with.meta.page_cursoruntil it is absent. - Safe query encoding: Use
curl --get --data-urlencodefor bracketed filters such asfilter[search]; this avoids shell globbing and preserves spaces. - Delete semantics: Deleting an inbox soft-deletes it, reserves its address, and returns
204with no response body.
Operational Caveats
- Thread identity is composite. Treat every thread as
(inbox_id, thread_id), not asthread_idalone. Inbox-scoped routes encode both values in the path. Account-wideGET /email_threads/{thread_id}requiresinbox_idas a query parameter. - Labels are not tags. Labels are mutable mailbox state such as
spam,promos, oraccount_alerts; tags are immutable billing and reporting attribution set when outbound mail is sent. Label mutation routes are not yet available through the gateway. - Sender filters are case-insensitive. Entries are normalized to lowercase. Exact addresses and
@domain.comdomain wildcards are accepted. Blocklist matches beat allowlist matches. Empty or absent lists accept all senders. - Reply and forward use the inbox domain. The action sends from the inbox address through the standard email send pipeline. The inbox must resolve to a valid configured sending domain.
- Search is PostgreSQL full-text search.
filter[search]searches subject, plain-text body, and HTML body; it is not a literal substring filter. Usefilter[from]orfilter[subject]for case-insensitive literal substrings.
Reference Use Rules
Do not invent Telnyx parameters, enums, recipient shapes, response fields, or webhook fields.
- If a parameter or response field is not shown inline, read references/api-details.md before writing code.
- Before composing filters or cursor loops, read request and query parameters.
- Before relying on a message, thread, or action response field, read response schemas.
- Before implementing an inbound handler, read webhook guidance and the Telnyx webhook documentation.
Core Tasks
Create an inbox
Create an inbox on an account-owned inbound-enabled domain. Both body fields are
optional: omit domain_id to use the shared inbound subdomain and omit username to
generate a unique local part.
POST /email_inboxes
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | No | Local part, normalized to lowercase; 1-64 characters using letters, digits, dots, hyphens, and underscores. |
domain_id | UUID | No | Account-owned inbound-enabled domain. Omit for the shared inbound subdomain. |
curl -sS \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "support",
"domain_id": "22222222-2222-2222-2222-222222222222"
}' \
"$TELNYX_API_BASE/email_inboxes"
Primary response fields: .data.id, .data.address, .data.status,
.data.domain_id,