/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

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

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_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](references/api-details.md) before writing code.
• Before composing filters or cursor loops, read [request and query parameters](references/api-details.md#request-and-query-parameters).
• Before relying on a message, thread, or action response field, read [response schemas](references/api-details.md#response-schemas).
• Before implementing an inbound handler, read [webhook guidance](references/api-details.md#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`,