Start for free
Mailboxes

List an identity's addresses

GET
/api/v1/identities/{identityId}/addresses

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 permittedFrom, which is the sendability contract and carries tag patterns.

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

identityId*string

Identity ULID identifier

Response Body

The identity's addresses

application/json
  1. response
addresses*array<string>

Lowercased addresses routed to this identity — its primary address first, then its route rows, deduplicated. Empty for an identity with no addresses at all (a calendar-only identity), which is an honest answer and not an error

Example Request
curl -X GET 'https://api.open.email/api/v1/identities/string/addresses'
Example Response
{
  "addresses": [
    "string"
  ]
}

Delete a mailbox DELETE

Soft-deletes a mailbox with a 7-day retention window for recovery. Pass purge=true to immediately queue the mailbox for permanent deletion.

Get mailbox details and usage statistics GET

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