Skip to main content
GET
List mailboxes

Authorizations

x-api-key
string
header
required

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

Query Parameters

workspaceId
string

Filter by workspace id (session users). API keys ignore cross-workspace values and stay on the key’s workspace.

Response

Mailbox list

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