Skip to the documentation
Knowledge base

Roles & permissions levels

A role says what somebody may do; an address grant says what they may do it to.

Details

  • Two grants per person, and both have to agree before anything happens. The ROLE, set in Settings → Members, says what they may DO in the workspace: read mail, send it, edit templates, add a domain, mint an API key. The address GRANT, set from the Share control on the address row, says which ADDRESSES they may do it to, as read-only or read-and-send. Somebody holding a role with sending in it and no addresses can send from nothing; somebody holding every address in the workspace under a read-only grant can send from none of them either.
  • Six roles exist without anybody creating them, and every workspace has the same six, so “Admin” means the same thing here as it does in the docs and on the API. Owner, Admin, Member and Viewer are a ladder: each holds everything the next one does, so demoting somebody narrows what they can reach rather than swapping it for a different slice. Developer and Billing are not rungs on that ladder. Developer builds integrations, holding API keys, webhooks, templates and sending while reading none of the workspace’s mail, and Billing sees the plan and the invoices, can change the plan and the payment details on them, and reads mailbox settings without being able to write one. Their permissions are editable: a workspace that would rather its members did not write templates unticks it, and the change lands on the next request anybody EXPLICITLY holding that role makes. Somebody whose role is still implied by an address grant made before roles existed keeps the shipped defaults until they are given one outright. So are their names: a workspace that runs on Ops and On-call renames them and is describing itself, which is the point.
  • Owner is the exception in every direction: not editable, not deletable, not assignable. It describes the account the workspace is keyed on and holds every permission, including ones added in a later release, which is why its list is computed rather than stored. Handing the workspace to somebody else is a transfer rather than a role change, and there is nothing here that does one.
  • Past those, a workspace writes its own, up to 24 in total, by ticking permissions out of the same grouped matrix. Ticking implies: “edit templates” stores “read templates” alongside it, because a role that can edit a template it cannot open is a checkbox somebody forgot rather than a policy anybody means. Deleting a role that people or API keys hold asks where to move them to and refuses rather than guessing. A key whose role vanished would fall back to no ceiling at all, which is wider than the role that just went.
  • An API key can be issued against a role, and the role is a ceiling rather than a second grant: what the key may do is its own scopes intersected with the role’s permissions, resolved on every request. A key created with sending on it and capped by Viewer cannot send, and narrowing a role revokes it live without the key having to be rotated. The assistant is held to the same list, and the MCP server builds a client’s tools from the caller’s permissions, so a viewer’s client has no sending tool in it at all, and every gated tool re-checks on the way in because a session can switch mailboxes after the list was built.