# Give another user access to this mailbox

Lets another identity in the same account open this mailbox — the shared team inbox and delegated-assistant case. The `rights` value decides what they may do with it.

Sending one grant replaces any previous grant for that identity, so this is how you widen or narrow access as well as how you create it. Both parties must belong to the same account, and a mailbox cannot be shared with itself.

Access takes effect immediately: rights are re-read on every request, so there is no cache to wait out — and revoking is equally immediate.

A grant covers reading and organising mail only. It never allows sending as the mailbox owner, and it never allows the recipient to re-share the mailbox or change grants.

## `PUT /api/v1/mailboxes/{mailboxId}/shares/{granteeIdentityId}`

### Path parameters

- `mailboxId` (string, required) — ULID of the mailbox whose access is being managed
- `granteeIdentityId` (string, required) — ULID of the identity being given (or losing) access

### Request body (required)

`application/json`

- `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, max 32 items) — 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. At most 32 folders may be named in one grant.

### Responses

**200** — The grant, as stored. `rights` comes back in canonical letters even if you sent a preset name, so you can display exactly what was granted

`application/json` → MailShare

- `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.

**400** — `validation_failed` — malformed body. `invalid_rights` — the rights value is not a known preset and not a valid letter set; the response carries an `invalidLetters` array naming the offending letters. `self_share_prohibited` — a mailbox cannot be shared with itself. `rights_not_allowed_on_folder_share` — a folder-scoped grant may only carry `lrswit` (read, private read/unread marks, write flags/keywords within the scope, file into a named in-scope folder, and trash out of the folder — never expunge or folder administration); the response names the offending letters and the allowed set. `empty_label_scope` — `labelScope` was an empty list, which would be a grant that can see nothing; use DELETE to revoke instead. `unknown_label` — one or more named folders do not exist in this mailbox; the response names them. `label_scope_too_large` — more folders were named than one grant may carry; the response carries the `max`. `invalid_label_scope` — a scope entry was not a folder identifier. `grantee_has_no_mail_store` — the grantee is an identity of this account without a mail store, which has no mail session to read a share in. `cross_account_share_refused` — the grantee belongs to a different account (system principals only; tenants receive 404 instead, so the API cannot be used to discover identities in other accounts)

`application/json` → ErrorOrValidation

**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, or the grantee identity does not exist or belongs to another account

`application/json` → ErrorBody

**409** — `mail_share_grantee_limit` or `mail_share_readable_store_limit`: a new grant would exceed the share fan-out cap; the response carries `max`. Existing grants remain editable.

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`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 PUT 'https://api.open.email/api/v1/mailboxes/{mailboxId}/shares/{granteeIdentityId}' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "rights": "string"
  }'
```

## TypeScript SDK

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

```ts
const mailShare = await openemail.mailboxShares.grant(mailboxId, granteeIdentityId, { rights: '…' })
```
