PutMailShareBody
The PutMailShareBody type of the TypeScript SDK, which mailboxShares.grant take or answer.
type PutMailShareBody = {
labelScope?: string[] | null
rights: string
}Fields
| Field | Type | Description |
|---|---|---|
labelScope | string[] | null | Optional. 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. |
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 | Give another user access to this mailbox |