# Get identity and bound store usage

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.

## `GET /api/v1/identities/{identityId}`

### Path parameters

- `identityId` (string, required) — Identity ULID identifier

### Responses

**200** — Identity and bound store details

`application/json` → Identity

- `accountId` (string | null, required) — Account ID owning this mailbox, or null
- `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
- `ephemeral` (boolean, required) — 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` (string | null, required) — 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, required) — 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, required) — Unique mailbox ULID
- `permittedRecipients` (array | null, required) — 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` (string | null, required) — Primary email address assigned to this mailbox, or null if none
- `quotaBytes` (integer | null, required) — Storage quota in bytes, or null for unlimited
- `receiveHold` ("paused" | "disabled" | null, required) — 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
  - _option 1: "paused" | "disabled"_
  - _option 2: null_
  - _option 3: null_
- `receiveHoldAt` (integer | null, required) — 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
- `receiveHoldPending` (boolean, required) — 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` (integer | null, required) — 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, required) — 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` ("disabled" | "paused" | null, required) — This mailbox's own operator enforcement: 'disabled' = permanent stop (403 sending_disabled), 'paused' = reversible hold (429 sending_paused), null = neither. System-written only
  - _option 1: "disabled" | "paused"_
  - _option 2: null_
  - _option 3: null_
- `sendMsgsPerDay` (integer | null, required) — Daily outbound message limit (null = platform default, 0 = unlimited)
- `sendMsgsPerHour` (integer | null, required) — Hourly (burst) outbound message limit (null = platform default, 0 = unlimited)
- `sendRcptsPerDay` (integer | null, required) — Daily outbound recipient limit (null = platform default, 0 = unlimited)
- `sendRcptsPerHour` (integer | null, required) — Hourly (burst) outbound recipient limit (null = platform default, 0 = unlimited)
- `suspendedAt` (integer | null, required) — 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}
- `suspensionPending` (boolean, required) — 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
- `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
- `facets` (IdentityFacets, required)
  - `mail` (object) — Mail store details if bound
    - `storeId` (string, required) — Mail store identifier
    - `expungedBytes` (integer <int64>) — Storage used by trash in bytes. Omitted when `unavailable` is true
    - `expungedCount` (integer <int64>) — Number of messages in trash. Omitted when `unavailable` is true
    - `messageCount` (integer <int64>) — Total number of active messages. Omitted when `unavailable` is true
    - `provisioned` (boolean) — True if the mail store has been initialized and may contain data. Omitted when `unavailable` is true
    - `unavailable` (boolean) — True when the store did not report its usage in time (a storage fault, or a slow start); `provisioned` and the counts are then omitted, never zero. The store is still bound. Retry later for the counts. Absent otherwise
    - `usedBytes` (integer <int64>) — Total mail storage used in bytes. Omitted when `unavailable` is true
  - `pim` (object) — PIM (calendar and contacts) store details if bound
    - `storeId` (string, required) — PIM (calendar/contacts) store identifier
    - `bytes` (integer <int64>) — Total storage used by calendar and contact objects in bytes. Omitted when `unavailable` is true
    - `collections` (integer <int64>) — Total number of calendar and addressbook collections. Omitted when `unavailable` is true
    - `objects` (integer <int64>) — Total number of calendar events and contact cards. Omitted when `unavailable` is true
    - `provisioned` (boolean) — True if the PIM store has been initialized and may contain data. Omitted when `unavailable` is true
    - `unavailable` (boolean) — True when the store did not report its usage in time (a storage fault, or a slow start); `provisioned` and the counts are then omitted, never zero. The store is still bound. Retry later for the counts. Absent otherwise
- `activityDay` (string | null) — 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

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Identity not found or not accessible to this principal

`application/json` → ErrorBody

**503** — temporary_failure: the identity's own holder could not answer its bound stores or its activity just now (under the object directory); retry after the Retry-After window

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/identities/{identityId}' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.identities.get`](/docs/sdks/typescript/identities/get)

```ts
const identity = await openemail.identities.get(identityId)
```
