Get mailbox details and usage statistics
Returns mailbox metadata, current storage usage, message counts, trash metrics, database size, and realtime socket connection stats.
bearerAuthAuthorizationBearer <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: [].
mailboxId*stringMailbox ULID identifier
Mailbox details and live usage stats
application/json- response
accountId*|Account ID owning this mailbox, or null
createdAt*integerCreation timestamp in epoch seconds
int64ephemeral*booleanWhether 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*booleanWhether 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*stringUnique 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?booleanPresent, 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
int64receiveHold*|||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
int64receiveHoldPending*booleanWhether 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*booleanWhether 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)
int64sendMsgsPerHour*|Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)
int64sendRcptsPerDay*|Daily outbound recipient limit (null = platform default, 0 = unlimited)
int64sendRcptsPerHour*|Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)
int64suspendedAt*|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}
int64suspensionPending*booleanWhether 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?integerCeiling limit for metadata database size in bytes
int64databaseSize?integerSQLite metadata database size in bytes
int64expungedBytes?integerStorage recoverable by emptying trash in bytes
int64expungedCount?integerNumber of soft-deleted messages in trash
int64liveSockets?integerCurrently connected live-events WebSocket connections
messageCount?integerTotal number of active messages
int64semanticFloor?|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
int64socketCapacity?integerMaximum allowed simultaneous WebSocket connections
socketsByClass?Active WebSocket connections broken down by client class
usedBytes?integerTotal storage used in bytes including trash
int64curl -X GET 'https://api.open.email/api/v1/mailboxes/string'{
"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
}List an identity's addresses GET
Returns every address routed to this identity — what it may be addressed AT, for matching an iCalendar ATTENDEE or ORGANIZER line. Distinct from /auth/verify's…
Get identity preferences GET
Returns client preferences (theme, language, signature, etc.) stored as a JSON object, along with the current version number for optimistic locking.