跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
效率与协作

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:

StatusMeaningAction
400Malformed request or send-time prerequisite failureFix the request; do not retry unchanged.
401Invalid or missing API keyReplace the key and retry.
403The account or inbox domain cannot sendCorrect permissions or sending-domain configuration.
404Resource is missing, deleted, foreign, or the sending domain could not be resolvedRe-list account-scoped resources; do not use the response to infer foreign resource existence.
422Validation failed or every action recipient was suppressedRead .errors[] and fix the referenced field.
429Rate limited or inbox-domain reputation suspended sendingHonor retry guidance for rate limits; reputation suspension requires remediation.
503Inbound storage, actions, or a dependency is unavailableRetry 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_KEY on every request.
  • Identifiers: inbox_id, message_id, and thread_id path parameters are Telnyx UUIDs. A message's RFC Message-ID appears separately as the message_id response field.
  • Pagination: Inbox listing uses page_size and page_cursor. Message and thread listing uses page[size] and page[after]. Continue with .meta.page_cursor until it is absent.
  • Safe query encoding: Use curl --get --data-urlencode for bracketed filters such as filter[search]; this avoids shell globbing and preserves spaces.
  • Delete semantics: Deleting an inbox soft-deletes it, reserves its address, and returns 204 with no response body.

Operational Caveats

  • Thread identity is composite. Treat every thread as (inbox_id, thread_id), not as thread_id alone. Inbox-scoped routes encode both values in the path. Account-wide GET /email_threads/{thread_id} requires inbox_id as a query parameter.
  • Labels are not tags. Labels are mutable mailbox state such as spam, promos, or account_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.com domain 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. Use filter[from] or filter[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

ParameterTypeRequiredDescription
usernamestringNoLocal part, normalized to lowercase; 1-64 characters using letters, digits, dots, hyphens, and underscores.
domain_idUUIDNoAccount-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,

阅读完整来源 ↗