Skip to main content
POST
Create inbox

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
mailboxName
string

Inbox local part (default: random)

Required string length: 3 - 30
displayName
string

Sender display name shown in the From header

Maximum string length: 200
domain
string

Domain for the inbox address. Defaults to your account domain (e.g. openmail.sh). Pass a verified custom domain you own to create the inbox on it (e.g. agent-mail.example.com). The domain must already be added and verified for your account; the account default never switches automatically.

webhookUrl
string

URL to receive signed webhook events for this inbox (e.g. inbound mail). Overrides the account-level webhook for this inbox only. A signing secret is generated and returned once in the response body.

podId
string

Pod to create the inbox in. Accepts the pod ID or your own clientId. Omit to place the inbox in your account's default pod.

Response

Inbox created

Inbox created

id
string

OpenMail inbox ID

podId
string

ID of the pod this inbox belongs to. Inboxes created without an explicit pod land in your account's default pod.

address
string<email>

Full email address

displayName
string | null

Sender display name

webhookUrl
string | null

URL that receives signed webhook events for this inbox, if set. Overrides the account-level webhook for this inbox only.

webhookSecret
string | null

Signing secret for this inbox's webhook. Only present in the response when the secret is generated or rotated (on create, on first setting a webhook URL, or via the rotate-secret endpoint) — it is never returned afterward.

createdAt
string<date-time>