Skip to main content
POST
Create mailbox

Authorizations

x-api-key
string
header
required

API key (sk-proj-…) from Settings → API Keys. Required for sold API calls outside the Mermail console.

Headers

Idempotency-Key
string

Optional key for a repeated attempt of the same mailbox create. Reuse it only for identical intent. It does not guarantee exactly-once execution; after a conflict or uncertain response, list mailboxes and resolve the exact normalized address before deciding whether to retry. Authenticated requests carrying this header have a 50 MiB request-fingerprint body limit; larger bodies return 413 idempotency_payload_too_large before the operation runs.

Required string length: 1 - 255

Body

application/json
email
string<email>
required

Mailbox address on an allowed Mermail or custom domain

name
string
required

Display name (also seeds settings.fromName)

Example:

"Acme Support"

workspaceId
string

Optional for a workspace-bound API key or MCP OAuth grant. If supplied, it must match the credential workspace.

Example:

"ws_01abc"

settings
object

Optional mailbox settings merged over defaults. For a verification-only inbox, set agentInbox to { "mode": "verification", "automationsEnabled": false }.

Response

Mailbox created

id
string

Hosted alias primary key (also accepted as mailboxId)

public_id
string<uuid>

Stable public route id; preferred mailboxId for agents and clients

workspace_id
string
email
string<email>
name
string
email_domain_id
string | null
inbound_provider
string

Provider configured for inbound delivery

outbound_provider
string

Provider configured for outbound delivery

provider_metadata
object
bucket_id
string | null
settings
object
disabled_at
string<date-time> | null

Non-null when the mailbox is disabled and should not be reused

disabled_reason
string | null

Reason the mailbox was disabled, when present

can_receive
boolean

Current receiving-readiness boolean derived from mailbox lifecycle, inbound-provider state, and the current Receiving MX verification state for custom domains

receiving_status
enum<string>

Current normalized inbound readiness. Custom-domain mailboxes become unavailable when their Receiving MX verification is not ready.

Available options:
ready,
disabled,
unavailable
welcome_onboarding_status
string

Internal welcome/demo-message workflow status. This is not inbound receiving readiness.

inbox_unread_by_category
object

Present on list endpoints only