# List mailboxes shared with you

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.

## `GET /api/v1/shared-mailboxes`

### Query parameters

- `labelScope` ("true" | "false") — 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

### 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

### Responses

**200** — 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` → object

- `sharedMailboxes` (SharedMailbox[], required)
  - `createdAt` (integer <int64>, required) — When the grant was first created, in epoch seconds
  - `granteeIdentityId` (string, required) — ULID of the identity the grant belongs to; always the caller's own identity
  - `mailboxId` (string, required) — ULID of the shared mailbox — the store to address when reading it
  - `ownerAddress` (string | null, required) — Primary email address of the mailbox owner, or null if the owner has none. Intended as the display name for the shared mailbox; fall back to the ULID when null
  - `rights` (string, required) — What the person you shared with is allowed to do, written as a set of letters in any order (stored and returned in the canonical order below). | Letter | Allows | | --- | --- | | `l` | See the mailbox in folder listings | | `r` | Read messages | | `s` | Change the read/unread mark — each person's own, never shared | | `w` | Change other flags, such as flagged or answered | | `i` | Put messages in: append, copy in, move in | | `k` | Create and rename labels | | `t` | Move messages to trash | | `e` | Permanently delete trashed messages | Instead of letters you may send a preset name, which is usually what you want: `read` or `read_only` (= `lrs`), `read_write` (= `lrswit`), or `admin` / `full` (= `lrswikte`, everything a grant can carry). Hyphenated spellings work too (`read-only`, `read-write`). **Three things no grant ever allows.** It does not allow sending mail as the mailbox owner. It does not allow deleting labels (`x`): that sends every message whose only label it was to the trash, which the owner may do with their own credentials but not hand to a delegate. And it does not allow re-sharing (`a`, RFC 4314's administration right): only the mailbox owner and account administrators can change who has access. Asking for `x` or `a` is refused with the letters named (an invalid_rights error), never quietly dropped. Letters outside the table (RFC 4314's `p`, and the obsolete `c` and `d`) are rejected and named back to you rather than ignored, so a grant never quietly means less than what you asked for. A repeated letter is rejected for the same reason.
  - `labelScope` (array | null) — Restrict the grant to specific FOLDERS, by name. Send `null` to share the whole mailbox — and note that OMITTING the field is a different request from sending null; see below. A folder-scoped grant may carry up to `lrswit` — everything `read_write` means. Within the granted folders it reads, marks read/unread privately, changes flags, files messages in, and trashes them. Two letters are rejected, naming themselves: `e` (permanently delete trashed messages), because a purge is irreversible and reaches messages filed in folders the holder cannot see; and `k` (create and rename folders), because a folder they created would not be inside their own grant. **What trashing means on a folder-scoped grant.** It removes the message from the folders they were granted — never from the mailbox. A message filed elsewhere as well stays exactly where you put it and simply leaves their view; a message that was only in their folders goes to Trash, where your normal 14-day undo reaches it. They can never permanently delete anything. **Filing in.** They must name one of their folders; there is no default (yours is INBOX, which is usually not one of theirs). Your filters do not run on what they file — a rule of yours could otherwise move it somewhere they cannot see, forward it, or send an auto-reply in your name. The grant follows the folder if it is RENAMED, and does not follow the name: deleting a folder and creating a new one with the same name does not revive an old grant. The grant follows the folder into DELETION too: deleting a folder removes it from every grant that names it, and a grant left naming no folders is revoked outright — a share dies with its last folder. An empty list is rejected on WRITE — revoke with DELETE instead. **Omitting the field and sending `null` are different requests.** On a grant that is already folder-scoped, omitting `labelScope` PRESERVES the existing folders and changes only the rights; sending an explicit `null` is what widens the grant to the whole mailbox. Widening is a deliberate act, so it has to be spelled — otherwise any client that does not know about folder scopes (IMAP `SETACL` among them, since the ACL wire format cannot express one) would silently replace a one-folder grant with a whole-store grant, and drop the `lrs` cap along with it. On READ an empty list can appear only on the OWNER's listing, and only as residue: it means every folder the grant named has since been deleted and the automatic revocation above could not run. Such a grant is dead — it matches nothing and gives access to nothing — and the owner's listing shows it so you can see it and remove it, while the shared-with-me listing never lists it. It is the one value you cannot send back unchanged: send DELETE, which is what a grant scoped to no folders already means. A folder-scoped viewer sees only these folders, and only their messages: listings, searches and conversations are all confined to them. Reachable over IMAP, the REST API and JMAP alike. **Changing a grant signs their clients out of sync.** Sync tokens on a folder-scoped grant are tied to the grant itself, so editing the folders or the rights makes every outstanding token stale exactly once: their clients re-list and carry on. Any live event stream they hold is closed at the same moment, so a narrowed grant takes effect immediately rather than when their connection happens to drop. Absent when the request passed `labelScope=false`, when the grant fell past the per-request folder-name render bound, or when the owner's store could not be reached to resolve names. Never an empty list here.

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

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/shared-mailboxes' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.mailboxShares.listSharedWithMe`](/docs/sdks/typescript/mailbox-shares/list-shared-with-me)

```ts
const result = await openemail.mailboxShares.listSharedWithMe()
```
