Inboxes

An inbox object:

{
  "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.

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

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.