---
title: "Create an email inbox"
method: POST
path: "/email_inboxes"
tags: ["Email Inboxes"]
---

# Create an email inbox

`POST /email_inboxes`

Creates an inbox on an inbound-enabled domain. When `domain_id` is omitted, Telnyx
allocates the account's shared inbound subdomain so the inbox is immediately usable
without customer DNS setup. When `username` is omitted, a unique username is generated.

## Request body

- CreateEmailInboxRequest — Both fields are optional. Omitting `username` generates one; omitting `domain_id` uses the account's shared inbound subdomain. Omitting both creates an instant inbox with a generated username.
  - `username` string — Inbox local part. Trimmed and lowercased before validation; the normalized value must be 1-64 characters, start and end with a letter or digit, and contain only letters, digits, dots, hyphens, and underscores. Generated when omitted.
  - `domain_id` string, uuid — Account-owned, inbound-enabled domain UUID. The account's shared inbound subdomain is allocated when omitted.

## Response `201`

Email inbox created.

- EmailInboxResponse
  - `data` EmailInbox, required
    - `id` string, uuid, required
    - `record_type` 'email_inbox', required
    - `address` string, email, required
    - `status` 'active' | 'paused', required
    - `domain_id` string, uuid, required
    - `domain` string, required — Domain name used by the inbox address.
    - `settings` object, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401` — Not authorized (10006).
- `422` — Inbox validation failed (10015).
- `503` — Service unavailable (10016), including an unavailable upstream dependency or unavailable Edge idempotency protection for a keyed request.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)