Skip to Content
GET
/api/v1/mailboxes/{mailboxId}

Returns mailbox metadata, current storage usage, message counts, trash metrics, database size, and realtime socket connection stats.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Response Body

Mailbox details and live usage stats

application/json
  1. response
accountId*|

Account ID owning this mailbox, or null

createdAt*integer

Creation timestamp in epoch seconds

Formatint64
ephemeral*boolean

Whether the mailbox was created DISPOSABLE (ephemeral: true at creation, immutable afterwards): its DELETE destroys it at once — no undo record, no 7-day window, the address free again immediately. False for every ordinary mailbox, whose DELETE keeps the window

groupAddress*|

When this identity is a GROUP PERSONA, the group address whose archive it keeps and which it may send as; null for every other identity. A persona has no primaryAddress, cannot be a route target, refuses its own DELETE (delete the group route instead) and its Sieve/rules writes, and is exempt from max_mailboxes

hasMailStore*boolean

Whether this identity has the mail capability. False for a calendar/contacts-only identity; true may also have a null primaryAddress. Derived from the directory row without reading or provisioning a store, not an indication that the store has been initialized or contains messages

id*string

Unique mailbox ULID

permittedRecipients*array<string>|

This mailbox's outbound recipient allowlist, written by system callers only. Entries are exact addresses (jo@acme.dev) or domain wildcards (*@acme.dev). null = unrestricted (the default); [] = may send to nobody. A submission outside the list is refused with 403 recipient_not_permitted (SMTP 550). Egress only: receiving is unaffected. A credential's own permittedRecipients may restrict sending further

primaryAddress*|

Primary email address assigned to this mailbox, or null if none

provisioningPending?boolean

Present, true, only while this identity's creation with messageWebhook or eventWebhook is still setting up: mail to its address and its calendar and contact writes are refused as temporary (503 temporary_failure) until it is, and the setup completes in the background. Absent for every other identity

quotaBytes*|

Storage quota in bytes, or null for unlimited

Formatint64
receiveHold*|||

The account owner's hold on this mailbox's RECEIVING, independent of suspension and of sendHold: 'paused' = senders are told to retry later (429 receiving_paused, SMTP 451; they give up after about four to five days, so a pause is for short interruptions), 'disabled' = mail to it is rejected at once (403 receiving_disabled, SMTP 550), null = receiving. Set with PATCH {"receiveHold": "paused"|"disabled"|null}, or on create

receiveHoldAt*|

When the current receiveHold was set (epoch seconds), restamped when the mode changes; null while receiving. The age of a pause is what decides whether it is still a pause: warn from the third day

Formatint64
receiveHoldPending*boolean

Whether the current receiveHold has not yet reached the mailbox's store: true right after a change still being applied (PATCH answered 202), false once it holds. Poll until false

retentionDays*|

The mailbox's OWN time-based retention window in days (null = none; the account default applies if one is set). The window in force, with a preview, is GET /mailboxes/:id/retention

semantic*boolean

Whether SEMANTIC (meaning-based) search is enabled for this mailbox: messages are embedded after delivery and GET /mailboxes/:id/search/semantic and …/messages/:id/similar answer. Tenant-set, gated by the account's plan; off by default. Turning it off DELETES the mailbox's embeddings

sendHold*|||

This mailbox's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only

sendMsgsPerDay*|

Daily outbound message limit (null = platform default, 0 = unlimited)

Formatint64
sendMsgsPerHour*|

Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)

Formatint64
sendRcptsPerDay*|

Daily outbound recipient limit (null = platform default, 0 = unlimited)

Formatint64
sendRcptsPerHour*|

Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)

Formatint64
suspendedAt*|

When the account owner suspended this mailbox (epoch seconds), null when it is not suspended. While suspended its logins are refused as a wrong password is, its sending is held (429 sending_paused) and its open sessions end; it still receives mail, and its owner keys can still read and administer it. Set with PATCH {"suspended": true|false}

Formatint64
suspensionPending*boolean

Whether the current suspendedAt has not yet reached every core gate it must: true right after a change whose enforcement is still being applied (PATCH answered 202), false once it holds everywhere. Poll until false

databaseLimitBytes?integer

Ceiling limit for metadata database size in bytes

Formatint64
databaseSize?integer

SQLite metadata database size in bytes

Formatint64
expungedBytes?integer

Storage recoverable by emptying trash in bytes

Formatint64
expungedCount?integer

Number of soft-deleted messages in trash

Formatint64
liveSockets?integer

Currently connected live-events WebSocket connections

messageCount?integer

Total number of active messages

Formatint64
semanticFloor?|

When semantic search is on: the earliest arrival time (epoch seconds) the backfill embeds — mail received before it is lexically searchable only. 0 = everything. Lower it with PATCH /identities/:id { semanticFloor } ("index older mail"); null when semantic search is off

Formatint64
socketCapacity?integer

Maximum allowed simultaneous WebSocket connections

socketsByClass?

Active WebSocket connections broken down by client class

usedBytes?integer

Total storage used in bytes including trash

Formatint64
Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string'
Example Response
{
  "accountId": "string",
  "createdAt": 0,
  "ephemeral": true,
  "groupAddress": "string",
  "hasMailStore": true,
  "id": "string",
  "permittedRecipients": [
    "string"
  ],
  "primaryAddress": "string",
  "provisioningPending": true,
  "quotaBytes": 0,
  "receiveHold": "paused",
  "receiveHoldAt": 0,
  "receiveHoldPending": true,
  "retentionDays": 0,
  "semantic": true,
  "sendHold": "disabled",
  "sendMsgsPerDay": 0,
  "sendMsgsPerHour": 0,
  "sendRcptsPerDay": 0,
  "sendRcptsPerHour": 0,
  "suspendedAt": 0,
  "suspensionPending": true,
  "databaseLimitBytes": 0,
  "databaseSize": 0,
  "expungedBytes": 0,
  "expungedCount": 0,
  "liveSockets": 0,
  "messageCount": 0,
  "semanticFloor": 0,
  "socketCapacity": 0,
  "socketsByClass": {
    "property1": 0,
    "property2": 0
  },
  "usedBytes": 0
}