Skip to Content
GET
/api/v1/accounts/{accountId}/storage-usage

Returns total stored bytes summed across all mailboxes in an account against the configured storage quota.

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

accountId*string

Account ULID identifier

Response Body

Current storage pool usage and limits

application/json
  1. response
accountId*string

Account ULID

complete*boolean

True when usedBytes is a full sum computed by this request. False for an account large enough that the walk is paged across passes: this request advanced the sweep by one pass and usedBytes is the last completed sweep's cached figure (null if none has finished yet). Poll until true.

computedAt*|

Timestamp when usage was calculated in epoch seconds, or null when no sum has ever been computed for this account. When complete is false this is the cached gauge's stamp, not this request's.

Formatint64
limitBytes*|

Effective storage limit in bytes (null = unlimited)

Formatint64
mailboxCount*integer

Total count of mailboxes owned by this account

Formatint64
storageLimitBytes*|

Configured storage limit override in bytes (null = default, 0 = unlimited)

Formatint64
usedBytes*|

Total storage used across all mailboxes in bytes including trash. NULL when complete is false and no full sweep has ever finished for this account: the sum is deliberately withheld rather than reported short, because a partial total would under-report storage.

Formatint64
Example Request
curl -X GET 'https://api.open.email/api/v1/accounts/string/storage-usage'
Example Response
{
  "accountId": "string",
  "complete": true,
  "computedAt": 0,
  "limitBytes": 0,
  "mailboxCount": 0,
  "storageLimitBytes": 0,
  "usedBytes": 0
}