# Create an inbox

POST /v1/inboxes

Source: https://cherami.to/docs/api/inboxes/create-inbox



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`POST /v1/inboxes`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

`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 [#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 [#request-body]

JSON object, at most 4 KiB in total.

### Schema: CreateInbox [#schema-createinbox]

| Field             | Required | Type           | Meaning and constraints                                                                                                                                                                                                                       |
| ----------------- | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local_part`      | Yes      | string         | 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`            | No       | string or null | Identifies the inbox within the account; not shown to recipients. At most 256 UTF-8 bytes; null or blank means none.                                                                                                                          |
| `sender_name`     | No       | string or null | Display name recipients see on the inbox's mail. At most 256 UTF-8 bytes; null or blank means none.                                                                                                                                           |
| `idempotency_key` | No       | 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. `pattern`: `^[A-Za-z0-9_-]{1,128}$` |

Unknown fields are rejected.

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

Save the payload as `request.json`, replacing the example values.

```json
{
  "local_part": "my-agent",
  "name": "Research",
  "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY"
}
```

```sh
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/inboxes" \
  --header "Authorization: Bearer $CHERAMI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

## Responses [#responses]

### HTTP 200 [#http-200]

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

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1]

[CreatedInbox](#schema-createdinbox)

### Part 2 [#part-2]

| Field                    | Required | Type   | Meaning and constraints                                                                                                 |
| ------------------------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `replayed`               | Yes      | `true` |                                                                                                                         |
| `idempotency_expires_at` | Yes      | string | When the key stops protecting retries. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "local_part": "my-agent",
  "address": "my-agent@cherami.to",
  "name": null,
  "sender_name": null,
  "created_at": "2026-10-01T00:00:00.000Z",
  "replayed": true,
  "idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}
```

### HTTP 201 [#http-201]

Created.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1-1]

[CreatedInbox](#schema-createdinbox)

### Part 2 [#part-2-1]

| Field      | Required | Type    | Meaning and constraints |
| ---------- | -------- | ------- | ----------------------- |
| `replayed` | No       | `false` |                         |

### HTTP 400 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-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).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 409 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[InboxError](#schema-inboxerror)

### HTTP 413 [#http-413]

`body_too_large`: Reduce the JSON request to the operation's body limit.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

`unsupported_media_type`: Send `Content-Type: application/json`.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: CreatedInbox [#schema-createdinbox]

| Field                    | Required | Type           | Meaning and constraints                                                                                                 |
| ------------------------ | -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id`                     | Yes      | string         | Cherami resource ID.                                                                                                    |
| `local_part`             | Yes      | string         |                                                                                                                         |
| `address`                | Yes      | string         |                                                                                                                         |
| `name`                   | Yes      | string or null |                                                                                                                         |
| `sender_name`            | Yes      | string or null |                                                                                                                         |
| `created_at`             | Yes      | string         | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$`       |
| `replayed`               | No       | boolean        | true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.        |
| `idempotency_expires_at` | No       | string         | When the key stops protecting retries. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

## Schema: InboxError [#schema-inboxerror]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields-1]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |
| `details` | No       | object |                                                                       |

#### `details` fields [#details-fields]

| Field              | Required | Type                                     | Meaning and constraints |
| ------------------ | -------- | ---------------------------------------- | ----------------------- |
| `allowance`        | Yes      | [InboxAllowance](#schema-inboxallowance) |                         |
| `increase_request` | Yes      | string                                   |                         |
| `policy_url`       | Yes      | string                                   |                         |

## Schema: InboxAllowance [#schema-inboxallowance]

| Field       | Required | Type            | Meaning and constraints |
| ----------- | -------- | --------------- | ----------------------- |
| `allowance` | Yes      | integer         | `minimum`: `0`          |
| `used`      | Yes      | integer         | `minimum`: `0`          |
| `remaining` | Yes      | integer         | `minimum`: `0`          |
| `unit`      | Yes      | `"inbox_slots"` |                         |

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
