# Inboxes

Source: https://docs.simail.ai/api/inboxes/

> List, create, get, update, delete and search inboxes. Inbox IDs are email addresses.

An inbox object:

```json
{
  "inbox_id": "shop-helper@simail.email",
  "pod_id": "pod_01JZX3S5V7W9X1Y3Z5A7B9C1D4",
  "display_name": "Shop Helper",
  "client_id": "shop-helper",
  "status": "active",
  "metadata": { "team": "support" },
  "created_at": "2026-10-18T16:41:07Z",
  "updated_at": "2026-10-18T16:41:07Z"
}
```

| Field | Notes |
|---|---|
| `inbox_id` | the email address; use it in every path |
| `pod_id` | the pod the inbox belongs to |
| `display_name` | sender name; outbound mail adds " via SiMail" |
| `client_id` | your idempotency handle, unique in the organization |
| `status` | `active` or `paused` (paused inboxes reject new mail and cannot send) |
| `metadata` | your JSON, up to a few KB; never store secrets here |

Guide: [Inboxes & pods](/inboxes/).

## List inboxes

`GET /v0/inboxes`

Permission `inbox_read`. Paginated (`limit`, `page_token`, `ascending`); returns `{ count, limit, next_page_token?, inboxes }`.
An inbox-scoped key sees only its own inbox.

## Create an inbox

`POST /v0/inboxes`

Permission `inbox_create`, organization- or pod-scoped key. Supports `Idempotency-Key`.

| Body field | Notes |
|---|---|
| `username` | optional; 3–32 characters of `a-z 0-9 . _ -`. A readable random name is generated if omitted. |
| `domain` | optional; defaults to your organization's simail mail domain |
| `display_name` | optional |
| `client_id` | optional; the same `client_id` returns the existing inbox instead of creating another |
| `pod_id` | optional; defaults to the key's pod, or the `default` pod |
| `metadata` | optional JSON object |

```sh
curl -s https://api.simail.ai/v0/inboxes \
  -H "Authorization: Bearer $SIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-shop-helper" \
  -d '{ "username": "shop-helper", "display_name": "Shop Helper", "client_id": "shop-helper" }'
```

`200 OK` with the inbox object. Publishes `inbox.created`.

| Status | `code` | When |
|---|---|---|
| 400 | `validation_error` | bad username or field |
| 403 | `missing_permission` | no `inbox_create`, an inbox-scoped key, or `reason: "inbox_limit"` when the organization has as many inboxes as its plan allows |
| 409 | `address_unavailable` | the address is taken, reserved, too similar to a reserved name, or retired |
| 409 | `idempotency_conflict` | the key was used with a different body |

## Get an inbox

`GET /v0/inboxes/{inbox_id}`

Permission `inbox_read`. `404 not_found` if it does not exist or is outside your scope.

## Update an inbox

`PATCH /v0/inboxes/{inbox_id}`

Permission `inbox_update`. Body: `display_name` and/or `metadata` (replaces the whole object).
Pausing and resuming an inbox is done by a human in the console.

## Delete an inbox

`DELETE /v0/inboxes/{inbox_id}`

Permission `inbox_delete`. The inbox stops receiving at once and its content is deleted. The address
is **retired**: your organization can restore it later, but it is never given to anyone else. Keys
scoped to the inbox stop working. Publishes `inbox.deleted`.

## Search inboxes

`GET /v0/inboxes/search?q=`

Permission `inbox_read`. Matches address, display name and `client_id`. Paginated.

## Not offered

`POST /v0/inboxes/{inbox_id}/authorize` returns `501 not_implemented`; use an inbox-scoped key.
Inboxes in a pod are also reachable under [`/v0/pods/{pod_id}/inboxes`](/api/pods/).