Skip to Content
PUT
/api/v1/mailboxes/{mailboxId}/shares/{granteeIdentityId}

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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

ULID of the mailbox whose access is being managed

granteeIdentityId*string

ULID of the identity being given (or losing) access

Request Body

application/json
  1. body
labelScope?array<string>|

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.

Itemsitems <= 32
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).

LetterAllows
lSee the mailbox in folder listings
rRead messages
sChange the read/unread mark — each person's own, never shared
wChange other flags, such as flagged or answered
iPut messages in: append, copy in, move in
kCreate and rename labels
tMove messages to trash
ePermanently 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.

Response Body

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
  1. response
createdAt*integer

When the grant was first created, in epoch seconds

Formatint64
granteeAddress*|

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*array<string>|

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

LetterAllows
lSee the mailbox in folder listings
rRead messages
sChange the read/unread mark — each person's own, never shared
wChange other flags, such as flagged or answered
iPut messages in: append, copy in, move in
kCreate and rename labels
tMove messages to trash
ePermanently 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.

Example Request
curl -X PUT 'https://api.open.email/api/v1/mailboxes/string/shares/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "rights": "string"
}'
Example Response
{
  "createdAt": 0,
  "granteeAddress": "string",
  "granteeIdentityId": "string",
  "labelScope": [
    "string"
  ],
  "mailboxId": "string",
  "rights": "string"
}