Skip to Content
GET
/api/v1/identities/{identityId}

Returns an identity with its bound stores (mail, calendars, contacts) and usage metrics. A bound store that cannot report its usage within a few seconds is still listed, marked unavailable: true with no counts; the rest of the identity is returned as usual.

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

Identity and bound store details

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

activityDay?|

The UTC date (YYYY-MM-DD) of this identity's latest recorded client activity, kept for the identity's lifetime; null means no recorded activity. Show it as returned, not converted to a local timezone. Omitted for a grant holder reading a mailbox shared with them and for a credential scoped below full: the owner's client history is theirs alone, like the client list itself

Formatdate
facets*
Example Request
curl -X GET 'https://api.open.email/api/v1/identities/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,
  "activityDay": "2019-08-24",
  "facets": {
    "mail": {
      "expungedBytes": 0,
      "expungedCount": 0,
      "messageCount": 0,
      "provisioned": true,
      "storeId": "string",
      "unavailable": true,
      "usedBytes": 0
    },
    "pim": {
      "bytes": 0,
      "collections": 0,
      "objects": 0,
      "provisioned": true,
      "storeId": "string",
      "unavailable": true
    }
  }
}