Manage Inboxes

Email inboxes let your application receive, read, and reply to email messages through the Telnyx API. Each inbox is an address on a verified sending domain that you own, or on Telnyx’s shared inbound subdomain for instant setup with no DNS configuration.

Create an inbox

Create an inbox by specifying a local part (username) and a domain you’ve already verified for inbound email. You can also omit domain_id to use the account’s shared inbound subdomain — no DNS setup required.

curl

curl -X POST https://api.telnyx.com/v2/email_inboxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "username": "support",
    "domain_id": "{domain_id}"
  }'

The response returns the inbox object with its full email address (e.g. support@yourdomain.com), status, and settings. To create an instant inbox on the shared subdomain, omit both fields:

curl

curl -X POST https://api.telnyx.com/v2/email_inboxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{}'

List and search messages

List messages in an inbox with optional search and filtering:

curl

curl -X GET "https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages?filter[search]=invoice" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can filter by:

Search text — filter[search] matches subject and message body
Sender — filter[from] matches the sender address
Labels — only messages with specific labels
Date range — messages received within a time window
Read/unread — filter by read status

Results are cursor-paginated, newest first. Message bodies are returned as text_body_url and html_body_url — URLs you fetch separately. Headers, attachments, and labels are included inline.

Reply to a message

Reply to a message with a single call. The original message’s In-Reply-To and References headers are set automatically:

curl

curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id}/actions/reply \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "Thanks for reaching out. We'll get back to you within 24 hours.",
    "html": "<p>Thanks for reaching out. We'll get back to you within 24 hours.</p>"
  }'

Use the reply_all action to reply to all recipients. Both text and html are optional, but at least one must be present.

Forward a message

Forward a message to new recipients. The forwarded message body is prepended with your optional note:

curl

curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id}/actions/forward \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": [{"email": "billing@company.com"}],
    "text": "Forwarding this for your review."
  }'

Drafts

Create a draft, update it, and send it when ready:

curl

# Create a draft
curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/drafts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": [{"email": "client@example.com"}],
    "subject": "Proposal follow-up",
    "text_body": "Hi, following up on our discussion..."
  }'

# Send the draft
curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/drafts/{draft_id}/send \
  -H "Authorization: Bearer YOUR_API_KEY"

You can also create a reply draft linked to a specific message using the POST /email_inboxes/{inbox_id}/messages/{message_id}/drafts endpoint.

Threads

Messages are grouped into threads by conversation. List threads in an inbox:

curl

curl -X GET https://api.telnyx.com/v2/email_inboxes/{inbox_id}/threads \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a thread with a page of its messages:

curl

curl -X GET https://api.telnyx.com/v2/email_inboxes/{inbox_id}/threads/{thread_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

You can also list threads across all inboxes in the account with GET /email_threads.

Labels

Organize messages and threads with labels:

curl

# Add labels to a message
curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id}/labels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"labels": ["urgent", "billing"]}'

# Remove labels
curl -X DELETE https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id}/labels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"labels": ["urgent"]}'

Labels are mutable string tags — use them for categories, priority, workflow state, or anything your application needs. Thread labels are managed with the equivalent /threads/{thread_id}/labels endpoints.

Sender filters

Control which senders can deliver to an inbox. Set a top-level type of allowlist or blocklist, and provide entries as an array of strings — exact email addresses or @domain wildcards:

curl

# Allow only specific senders
curl -X POST https://api.telnyx.com/v2/email_inboxes/{inbox_id}/filters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "type": "allowlist",
    "entries": [
      "trusted@partner.com",
      "@partner-domain.com"
    ]
  }'

Use PUT to replace all filters at once, or DELETE to remove specific entries.

Mark messages as read or unread

Update the read state of a message. Set read_at to true for the current timestamp, an ISO-8601 string for a specific time, or null to mark as unread:

curl

curl -X PATCH https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"read_at": true}'

Getting Started

Sending Email

Inboxes

Domains & Validation

Deliverability

Templates & Suppression

Events & Webhooks

Manage Inboxes

Create an inbox

List and search messages

Reply to a message

Forward a message

Drafts

Threads

Labels

Sender filters

Mark messages as read or unread

​Create an inbox

​List and search messages

​Reply to a message

​Forward a message

​Drafts

​Threads

​Labels

​Sender filters

​Mark messages as read or unread

Create an inbox

List and search messages

Reply to a message

Forward a message

Drafts

Threads

Labels

Sender filters

Mark messages as read or unread