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

# Create an inbox

`POST /v1/inboxes`

## Request

- Base URL: `https://api.mailfixture.com`
- URL: `https://api.mailfixture.com/v1/inboxes`
- Auth: HTTP bearer

Creates a receiving address. The body is optional: with no body the inbox gets a random 10-character local part on the shared domain and no expiry. Creation draws on a second per-key bucket (burst 10, refills 10/minute) in addition to the general request budget — either can answer 429.

## Request body

- CreateInboxRequest: All fields optional; an empty or absent body creates a random address on the shared domain with no expiry.
  - `domain` string: A shared domain or one of the account's verified custom domains. Omit for the shared domain.
  - `local_part` string: Lowercased on input; must not start or end with a dot. Omit for a random 10-char local part.
  - `ttl_seconds` integer: Auto-expire the inbox after this many seconds (max 30 days). Expired inboxes 550-reject new mail and are swept hourly. Omit for no expiry.

## Response `201`

Inbox created.

- Inbox
  - `created_at` string, date-time, required
  - `domain` string, required
  - `email_address` string, required: `local_part@domain` — the address to send to.
  - `id` string, uuid, required
  - `local_part` string, required
  - `ttl_expires_at` string, date-time, nullable, required

## Other responses

- `400`: Invalid `local_part` (1–64 chars of [a-z0-9._-], must not start or end with a dot) or `ttl_seconds` out of range (60–2592000).
- `401`: Missing bearer token, malformed key, or unknown/revoked/invalid API key.
- `403`: Account frozen, or the plan's active-inbox cap is reached (free 25, solo 250, team 1000, scale 5000).
- `404`: `domain` names a domain that is neither shared nor owned by this account.
- `409`: That address already exists.
- `429`: Per-key rate limit exceeded. `Retry-After` says when the next request will be admitted; the RateLimit headers name the bucket that refused (`requests` or `creates`) with `r=0`.
- `500`: Unexpected server error. `detail` is null — internals are never leaked.
- `503`: No shared domain is configured on this deployment (only when `domain` was omitted).

---

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