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

# Create an inbox

`POST /v1/inboxes`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/inboxes`
- Auth: HTTP bearer

`local_part` becomes the address `local_part@cherami.to`. The address is permanent: it can't be renamed or moved to another domain. To move an agent to a new address, see [Change your agent's email address](https://cherami.to/docs/guides/change-email-address).

`name` identifies the inbox within the account and isn't shown to recipients; `sender_name` is the display name recipients see on its mail. Both are optional, can be [edited later](https://cherami.to/docs/api/inboxes/update-inbox) and need not be unique.

### Recover creation

Include an `idempotency_key` to make a retry safe. If the response is lost or you get a `5xx`, repeat the request with the same key and the original payload within 24 hours of your first attempt: a match returns `200` with `replayed: true` and the inbox as it is now, and creates nothing new.

A request refused with `400`, `address_unavailable` or `inbox_limit_reached` leaves its key unused. Use each key for one inbox, and don't switch to a new key or another address to get past an uncertain result.

After 24 hours, or without a key, [list inboxes](https://cherami.to/docs/api/inboxes/list-inboxes) and look for the address before creating again: an unkeyed repeat of a creation that succeeded returns `409 address_unavailable`.

## Request body

- CreateInbox
  - `local_part` string, required: The part before @cherami.to, lowercased: 1–64 letters, digits, hyphens or underscores, starting and ending with a letter or digit. Taken, reserved and retired addresses are unavailable.
  - `name` string, nullable: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
  - `sender_name` string, nullable: Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters.
  - `idempotency_key` string: Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again.

## Response `200`

A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.

- object
  - `id` string, required: Cherami resource ID.
  - `local_part` string, required
  - `address` string, required
  - `name` string, nullable, required
  - `sender_name` string, nullable, required
  - `created_at` string, date-time, required: UTC timestamp with milliseconds.
  - `replayed` true, required: true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.
  - `idempotency_expires_at` string, date-time, required: When the key stops protecting retries.

## Other responses

- `201`: Created.
- `400`: `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_inbox`: Creation takes only `local_part`, `name`, `sender_name` and `idempotency_key`; an edit takes at least one of `name` and `sender_name`, and nothing else. `invalid_local_part`: Use 1–64 letters, digits, hyphens or underscores for `local_part`, starting and ending with a letter or digit. `invalid_name`: Use plain text without control characters, at most 256 UTF-8 bytes after trimming. The message names the field. `invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.
- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `404`: `not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
- `409`: `address_unavailable`: The address is in use, reserved or retired. Choose another `local_part`. `inbox_limit_reached`: All inbox slots are in use; `error.details.allowance` has the counts. Use an existing inbox, or [request more slots](https://cherami.to/docs/guides/support) rather than deleting an inbox still in use. `idempotency_conflict`: The key was first used with different input. To recover that request, repeat it with its original inbox and payload; a different request needs its own key. `idempotency_result_unavailable`: The key already created an inbox, draft or send whose result has since been deleted. Nothing new was created or sent; do not repeat the request under a new key. If a sent message is still in Trash, restore it to read the outcome.
- `413`: `body_too_large`: Reduce the JSON request to the operation's body limit.
- `415`: `unsupported_media_type`: Send `Content-Type: application/json`.
- `500`: `internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

---

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