Skip to Content

The PutMailShareBody type of the TypeScript SDK, which mailboxShares.grant take or answer.

type PutMailShareBody = {
  labelScope?: string[] | null
  rights: string
}

Fields

FieldTypeDescription
labelScopestring[] | nullOptional. 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.
rightsstringWhat 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

MethodWhat it does
mailboxShares.grantGive another user access to this mailbox

On this page