# List who has access to this mailbox

Returns everyone this mailbox has been shared with, oldest grant first, each with the rights they hold. This is the owner's side of sharing; to list mailboxes shared WITH you, use `GET /shared-mailboxes` instead.

The full list is always returned — grants are bounded by the account's own membership, so there is no paging.

## `GET /api/v1/mailboxes/{mailboxId}/shares`

### Path parameters

- `mailboxId` (string, required) — ULID of the mailbox whose access is being managed

### Responses

**200** — Everyone with access to this mailbox, oldest grant first

`application/json` → object

- `shares` (MailShare[], required)
  - `createdAt` (integer <int64>, required) — When the grant was first created, in epoch seconds
  - `granteeAddress` (string | null, required) — Primary email address of the identity that was given access, or null if it has none. Returned alongside the ULID so a client (notably IMAP GETACL, whose identifiers are addresses) does not have to look up each grantee separately
  - `granteeIdentityId` (string, required) — ULID of the identity that was given access
  - `labelScope` (array | null, required) — 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. Null means the whole mailbox is shared.
  - `mailboxId` (string, required) — ULID of the mailbox being shared (the owner's store)
  - `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.

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

`application/json` → ErrorBody

**404** — `not_found` — the mailbox does not exist or is not yours to manage

`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/mailboxes/{mailboxId}/shares' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

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

```ts
const result = await openemail.mailboxShares.list(mailboxId)
```
