Telnyx Email Inbound 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:

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

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, .data.domain, .data.created_at.

List inboxes

Lists non-deleted inboxes newest first with stable cursor pagination.

GET /email_inboxes

curl -sS --get \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'page_size=50' \
  "$TELNYX_API_BASE/email_inboxes"

# Next page: pass the previous response's .meta.page_cursor unchanged.
curl -sS --get \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'page_size=50' \
  --data-urlencode "page_cursor=$PAGE_CURSOR" \
  "$TELNYX_API_BASE/email_inboxes"

page_size defaults to 20 and accepts 1-250. An absent .meta.page_cursor means there is no next page.

Get an inbox

GET /email_inboxes/{id}

export INBOX_ID="11111111-1111-1111-1111-111111111111"

curl -sS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID"

Missing, deleted, and foreign inboxes return an opaque 404.

Delete an inbox

Soft-delete an inbox. Its address remains reserved, and list/get no longer return it.

DELETE /email_inboxes/{id}

curl -sS \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID"

Success is 204 No Content. Do not attempt to parse a success response body.

List and search inbound messages

Lists inbound messages newest first. Filters compose with stable cursor pagination.

GET /email_inboxes/{inbox_id}/messages

curl -sS --get \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'filter[search]=quarterly renewal' \
  --data-urlencode 'filter[unread]=true' \
  --data-urlencode 'filter[received_after]=2026-07-01T00:00:00Z' \
  --data-urlencode 'page[size]=25' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages"

Each result includes the Telnyx message UUID in .data[].id, the RFC header value in .data[].message_id, its .data[].thread_id, envelope addresses, body URLs, file metadata, labels, and read/received timestamps.

Mark a message read or unread

PATCH /email_inboxes/{inbox_id}/messages/{message_id}

Set read_at to true for server time, an ISO 8601 timestamp for explicit time, or null to mark unread. Repeating the same update is idempotent.

export MESSAGE_ID="55555555-5555-5555-5555-555555555555"

# Mark read at server time.
curl -sS \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"read_at": true}' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages/$MESSAGE_ID"

# Mark unread.
curl -sS \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"read_at": null}' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages/$MESSAGE_ID"

The response returns the updated inbound message in .data.

Reply to a message

Recipients are derived from the original Reply-To, falling back to From. Original Cc recipients are not included. Telnyx adds the Re: subject prefix and threading headers.

POST /email_inboxes/{inbox_id}/messages/{message_id}/actions/reply

curl -sS \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks for the update. I will review it today."}' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages/$MESSAGE_ID/actions/reply"

At least one of text or html must contain non-whitespace content. Caller-supplied to, cc, and bcc are ignored. Success is 202; .data.id is the queued outbound message ID. Inspect optional .suppressed[] and the X-Telnyx-Reputation-Warning response header.

Reply all to a message

The To list starts with original Reply-To or From and includes original To recipients; Cc includes original Cc. The inbox address is excluded and recipients are de-duplicated case-insensitively. Bcc is empty.

POST /email_inboxes/{inbox_id}/messages/{message_id}/actions/reply_all

curl -sS \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<p>Everyone, please review the attached update.</p>"}' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages/$MESSAGE_ID/actions/reply_all"

The body rules, 202 response, suppression behavior, domain requirement, and threading behavior are the same as reply.

Forward a message

Supply at least one To recipient. Recipients may be email strings or objects with email and optional name. Telnyx prepends optional text/html notes to a generated forwarded-message block and applies the Fwd: subject prefix.

POST /email_inboxes/{inbox_id}/messages/{message_id}/actions/forward

curl -sS \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "owner@example.com", "name": "Account Owner"}],
    "cc": "audit@example.com",
    "bcc": ["archive@example.com"],
    "text": "FYI — please review this inbound request."
  }' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/messages/$MESSAGE_ID/actions/forward"

Success is 202. Partial suppression appears in .suppressed[]; if every recipient is suppressed, the request returns 422 and no message is sent.

List threads in one inbox

GET /email_inboxes/{inbox_id}/threads

curl -sS --get \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'page[size]=25' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/threads"

Thread summaries are newest first and include .id, .inbox_id, .subject, .message_count, .unread_count, .last_message_id, and .last_message_at. Although filter[label] can filter existing labels, label mutation is not yet available.

Get a thread and its messages in one inbox

Returns inbound and outbound messages interleaved in chronological order. Message pages are bounded; follow .meta.page_cursor with page[after].

GET /email_inboxes/{inbox_id}/threads/{thread_id}

export THREAD_ID="33333333-3333-3333-3333-333333333333"

curl -sS --get \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode 'page[size]=50' \
  "$TELNYX_API_BASE/email_inboxes/$INBOX_ID/threads/$THREAD_ID"

Use .data.messages[].direction to distinguish inbound and outbound entries. Never use the thread ID without retaining its inbox ID.