---
title: "Create an inbox"
method: POST
path: "/inboxes"
tags: ["inboxes"]
---

# Create an inbox

`POST /inboxes`

## Request

- Base URL: `https://dash.mailsocket.app/api/v1`
- URL: `https://dash.mailsocket.app/api/v1/inboxes`
- Auth: HTTP bearer

Creates a new inbox with an optional `label`. Returns `201` with a
`Location` header pointing at the new inbox, or `409` when the plan
limit is reached (`plan_limit_reached`) or after allocation retries are
exhausted (`conflict`).

## Headers

- `Idempotency-Key` string

## Request body

- InboxWrite
  - `label` string: Optional inbox label.
  - `routing_key` string: Optional custom slug (the local-part of the inbox address). Input is normalized to lowercase BEFORE validation, so callers may pass either case (e.g. `MyCustomBox` is accepted and stored as `mycustombox`); the pattern above matches the raw (pre-normalized) input character set. Must start with a letter or digit and contain only `A-Za-z`, `0-9`, `_`, `-` after that (3-64 chars total). When omitted, a random routing key is minted. Returns `409 slug_taken` if another account already owns it (checked case-insensitively, after lowercasing), or `422 validation_error` if it fails the pattern/length constraints or is a reserved key. The reserved-key blocklist applies ONLY when `domain` is omitted (shared domain); it is not enforced on a custom domain (the owner controls their whole namespace there).
  - `domain` string: Optional public id (`dom_...`) of a verified custom domain owned by the same account. Omitted (or blank) creates a shared `in.inboxpipe.net` inbox. Returns `422 domain_not_found_or_unverified` if the domain does not exist, is not owned by the caller, or is not `verified`; `403 byod_disabled` if custom domains are not enabled for the account.
  - `public` boolean: Opt-in flag making the inbox's recent messages readable with no auth via `GET /public/emails/{email}/messages`. Defaults `false`. Never set it on an inbox that receives real user signups. Shared-domain inboxes only: `true` combined with a non-blank `domain` returns `422 public_not_allowed_on_custom_domain`. Anyone holding the address can read up to 20 recent messages, including OTPs (never the body or metadata).
  - `metadata` object: Optional correlation metadata (e.g. `{"run": "ci-123"}`), echoed back on every OWNER-facing read surface (inbox get/list, message poll/latest/wait/batch, webhook payload). NEVER exposed on either anonymous surface (the instant `.md` endpoints or `GET /public/emails/{email}/messages`). Must be a JSON object (`422 metadata_must_be_object` otherwise), at most 4096 bytes of compact UTF-8 JSON and at most 50 top-level keys (`422 metadata_too_large` otherwise). Omitted defaults to `{}`.

## Response `201`

Inbox created.

- object
  - `data` Inbox, required
    - `id` string, required: The inbox public ID.
    - `label` string, required
    - `address` string, required: The full inbound email address.
    - `is_enabled` boolean, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `metadata` object, required: Your correlation metadata, `{}` when unset. Never returned by unauthenticated endpoints.

## Other responses

- `400`: The `Idempotency-Key` header is empty, longer than 255 characters, or not printable ASCII, or the request body is too large to read with an `Idempotency-Key`.
- `401`: Missing or invalid API key.
- `403`: Account is not permitted to use the API.
- `409`: Plan limit reached (`plan_limit_reached`), custom `routing_key` already claimed by another account (`slug_taken`), allocation conflict (`conflict`), or a request with the same `Idempotency-Key` is still running (`idempotency_in_progress`).
- `415`: Request media type is not supported.
- `422`: The `Idempotency-Key` was already used with a different body or endpoint (`idempotency_key_reused`), or the request body failed validation.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/mailsocket/apis/mailsocket-api.md) · [All operations](https://skmtc.dev/mailsocket/apis/mailsocket-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailsocket/apis/mailsocket-api/revisions/e579500dfb7e?raw)