# MailShare

The MailShare type of the TypeScript SDK, which mailboxShares.grant and mailboxShares.list take or answer.

```ts
type MailShare = {
  createdAt: number
  granteeAddress: string | null
  granteeIdentityId: string
  labelScope: string[] | null
  mailboxId: string
  rights: string
}
```

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `createdAt` | `number` | When the grant was first created, in epoch seconds |
| `granteeAddress` | `string` \| `null` | 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` | ULID of the identity that was given access |
| `labelScope` | `string[]` \| `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. Null means the whole mailbox is shared. |
| `mailboxId` | `string` | ULID of the mailbox being shared (the owner's store) |
| `rights` | `string` | 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. |

## Used by

| Method | What it does |
| --- | --- |
| [`mailboxShares.grant`](/docs/sdks/typescript/mailbox-shares/grant) | Give another user access to this mailbox |
| [`mailboxShares.list`](/docs/sdks/typescript/mailbox-shares/list) | List who has access to this mailbox |
