---
title: "Create inbox"
method: POST
path: "/v1/inboxes"
tags: ["inboxes"]
---

# Create inbox

`POST /v1/inboxes`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/inboxes`
- Auth: HTTP bearer

Create a new email inbox. Optionally set a sender display name.

## Request body

- object
  - `mailboxName` string: Inbox local part (default: random)
  - `displayName` string: Sender display name shown in the From header
  - `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.
  - `forwardTo` string, email: Email address that receives a copy of inbound messages, e.g. your own Gmail. Members of your organisation are confirmed at once; any other address is emailed a confirmation link and nothing is forwarded until they click it (`forwardStatus` is `pending` meanwhile). Spam and bulk mail are never forwarded. Replies go to the original sender.
  - `forwardWhen` 'always' | 'needs_human' | 'webhook_failed': When to forward. `always` (default); `needs_human` only mail the agent should not auto-handle (`autoReplyable` false); `webhook_failed` only once webhook delivery has exhausted its retries or there was no webhook or WebSocket to deliver to.
  - `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 `201`

Inbox created

- Inbox
  - `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, nullable: Sender display name
  - `webhookUrl` string, nullable: URL that receives signed webhook events for this inbox, if set. Overrides the account-level webhook for this inbox only.
  - `webhookSecret` string, nullable: 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.
  - `forwardTo` string, nullable: Address that receives copies of this inbox's inbound mail, if set.
  - `forwardWhen` 'always' | 'needs_human' | 'webhook_failed' | 'null', nullable: Which inbound mail is forwarded. Null when forwarding is not set.
  - `forwardStatus` 'pending' | 'active' | 'disabled' | 'null', nullable: `pending` until the address confirms via the emailed link (members of your organisation are confirmed at once); `active` once copies are flowing; `disabled` when forwarding paused itself after the address hard-bounced repeatedly or complained — set `forwardTo` again to resume. Null when forwarding is not set.
  - `createdAt` string, date-time

## Other responses

- `400`: Invalid mailbox name, `domain` is not verified or not available in the selected pod, or `podId` does not match a pod in your account
- `402`: Pro plan: inbox creation is paused because the account's monthly spend limit was reached
- `409`: Address already in use, or the mailbox name is reserved
- `422`: Plan inbox limit reached, `webhookUrl` failed validation (`invalid_webhook_url`), or forwarding settings were rejected (`invalid_forward_to`, `forward_to_is_openmail_address`, `forward_verification_cooldown`, `invalid_forward_when`, `forward_when_requires_forward_to`)
- `429`: Rate limit exceeded (100 inbox creations/day, or 10 forwarding confirmation emails/hour — `forward_verification_limit`)

---

[API](https://skmtc.dev/openmail/apis/openmail-api.md) · [All operations](https://skmtc.dev/openmail/apis/openmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openmail/apis/openmail-api/revisions/b943eecca7e2?raw)