Organizations
Update who a mailbox is shared with (admin)
Mailboxes are created and linked by the OAuth connect flow; this sets the only admin-managed field, grants - who else may send from the mailbox beyond its link. Mailbox grants carry send only: a read verb is refused with a 400 (read access to a mailbox cannot be granted yet). grants, when present, REPLACES the whole list ([] removes every grant); when absent nothing changes. Every principal must be a user, user group or department of the organization and may appear once; new or changed grants are stamped with the calling admin, unchanged ones keep their original grantedBy/grantedAt. Returns the updated mailbox (tokens excluded). Admin or SuperAdmin.
Authorization
bearerAuth In: header
Path Parameters
The organization that owns the mailboxes.
_id of the EmailAccount.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/organizations/string/email-accounts/string" \ -H "Content-Type: application/json" \ -d '{ "grants": [ { "principalType": "user", "principalId": "6650a1b2c3d4e5f6a7b8c9d4", "verbs": [ "send" ] }, { "principalType": "department", "principalId": "6650a1b2c3d4e5f6a7b8c9d3", "verbs": [ "send" ] } ] }'{ "success": true, "account": { "_id": "665f1a0c0e0a4b001a2c9f50", "organizationId": "64ee9a8b1e7f2a0011223344", "provider": "gmail", "providerAccountId": "107834928382923743821", "emailAddress": "ops@acme.example", "isActive": true, "historyId": "123456", "watchExpiration": "2026-05-25T00:00:00.000Z", "createdAt": "2026-05-01T09:00:00.000Z", "updatedAt": "2026-05-18T12:00:00.000Z" }}