Skip to Content
GET
/api/v1/shared-mailboxes

Returns every mailbox belonging to someone else that you have been given access to, oldest grant first, each with the rights you hold on it. Use the returned mailboxId to read that mailbox through the ordinary mailbox endpoints.

There is no mailbox in the path: the answer is scoped to whoever is authenticated. A mailbox credential lists its own grants. An account credential is not an identity and receives an empty list — to see one member's shared mailboxes, ask with that member's credential. A system credential must name the identity it is acting for in the X-Acting-Identity header, and without it receives an empty list rather than every grant on the deployment.

An empty list is the normal answer for someone nothing has been shared with; it is never an error. The full list is always returned — there is no paging.

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: [].

Query Parameters

labelScope?string

Set false to skip resolving each folder-scoped grant's folder NAMES, omitting labelScope from every row. Rendering costs one read of the owner's folder list per distinct owner who granted you folder-scoped access, so a client that does not display folder names — notably one calling this per IMAP LIST — should turn it off. The field is OMITTED rather than emptied: null already means whole mailbox, so absent is the only honest way to say 'not computed'. Note that skipping the render also skips the dead-grant filter: a grant whose folders were all deleted (normally revoked by the folder delete itself, and hidden here if that cleanup could not run) is only detectable BY rendering, so with labelScope=false such residue is listed like any other grant. Defaults to rendering

Value in"true""false"

Header Parameters

x-acting-identity?string

System credentials only: the ULID of the identity to answer for. Ignored for mailbox and account credentials, which already identify the caller. Omitting it on a system credential returns an empty list

Response Body

Mailboxes shared with you, oldest grant first. Empty when nothing is shared with you, or when the caller is not an identity (see above)

application/json
  1. response
sharedMailboxes*array<>
Example Request
curl -X GET 'https://api.open.email/api/v1/shared-mailboxes'
Example Response
{
  "sharedMailboxes": [
    {
      "createdAt": 0,
      "granteeIdentityId": "string",
      "labelScope": [
        "string"
      ],
      "mailboxId": "string",
      "ownerAddress": "string",
      "rights": "string"
    }
  ]
}