Inboxes

An inbox is one email address plus its threads, messages, drafts and labels. Inbox IDs in the API are the address itself (shop-helper@simail.email); SiMail resolves it to an internal ID on every call.

Create

POST /v0/inboxes
Idempotency-Key: create-shop-helper
Content-Type: application/json

{
  "username": "shop-helper",
  "display_name": "Shop Helper",
  "client_id": "shop-helper",
  "metadata": { "team": "support" }
}

Field	Notes
username	optional; a readable random name is generated if omitted
domain	optional; defaults to your organization’s SiMail mail domain
display_name	shown as the sender name (outbound mail adds “ via SiMail”)
client_id	optional idempotency handle; the same client_id returns the same inbox
metadata	free-form JSON for your own bookkeeping; do not store secrets here

Requires inbox_create on an org- or pod-scoped key. Creating more inboxes than your plan allows returns 403 missing_permission with reason: "inbox_limit".

Address rules

• 3–32 characters from a-z, 0-9, ., _, -; no leading, trailing or consecutive dots.
• Lowercased. A +tag suffix is never part of the address (SiMail uses it for reply tokens).
• Reserved names (postmaster, abuse, security, admin, noreply, …) and names that look like them (mixed scripts, 0/o, 1/l) are refused.
• Addresses are never reassigned to another organization. Deleting an inbox retires its address; your organization can restore it later, but nobody else can ever take it. A taken or retired name returns 409 address_unavailable.

Read, update, delete

Method and path	Permission
GET /v0/inboxes	inbox_read
GET /v0/inboxes/{inbox_id}	inbox_read
PATCH /v0/inboxes/{inbox_id} (display_name, metadata)	inbox_update
DELETE /v0/inboxes/{inbox_id}	inbox_delete
GET /v0/inboxes/search?q=	inbox_read

Listings are paginated: limit (1–200, default 50), page_token (opaque; bound to your key’s scope and query) and ascending. Responses look like { "count": 2, "limit": 50, "next_page_token": "…", "inboxes": [ … ] }.

An inbox can be paused in the console; a paused inbox rejects new mail and cannot send until resumed.

Pods

A pod groups inboxes, for example one pod per customer or per agent fleet. Each organization has a default pod. Pod-scoped keys see only that pod. Humans create and delete pods in the console; keys can read them:

GET /v0/pods, GET /v0/pods/{pod_id}, GET /v0/pods/{pod_id}/inboxes, and the pod variants of inbox, thread and draft endpoints.

Not available

Custom domains (/v0/domains) are not offered (501 not_implemented, reason: "not_planned"). Calendar, files and connected accounts are planned for a later phase (reason: "phase_2").