メンバー

Everybody with access to this workspace, the owner first and the rest by email. A page at a time: follow nextCursor while hasMore is true to read everybody.

Each row carries BOTH axes and a client must not collapse them. role is what somebody may do; addresses is what they may do it to, one entry per address with its own access. Someone with emails:send and an empty addresses may send from nothing, and someone holding every address under a viewer role may send from none of them either. The send path checks both, so a screen showing one of them will confidently explain the wrong refusal.

The one exception is addresses:all. Somebody whose permissions hold it reaches every address on every domain of the workspace, including ones added later, and sends as any of them when permissions also holds emails:send, whatever addresses and domains list. Those two still hold only direct grants, which such a member may have kept from before or been given since, or none at all. Read reach from permissions first, and from those arrays only when it lacks addresses:all.

Watch for implied: true. It means nobody chose that role: sharing shipped long before roles did, so a great many people have address grants and no membership row, and the widest grant they hold names a built-in rather than leaving them locked out until a backfill has run. A PATCH is what turns the inference into a decision.

The owner IS in this list, as the first row, marked isOwner: true. They are the thing the workspace is keyed on, they hold every permission by definition, and POST, PATCH and DELETE all refuse them with member_is_owner. Exclude isOwner when you are counting seats.

Requires the members:read scope.

Invites somebody to the workspace. Whether or not the address already has an OpenEmail account, the answer is an invitation and a 202, never a member: nobody is put into a workspace without accepting, and this endpoint is held to the same rule as the app.

The invitation carries the role, the addresses and the whole domains you name, and grants exactly those the moment it is accepted. Nothing is granted before that. An address invited in the last ten minutes answers invitation_too_soon, and asking twice refreshes the one invitation rather than sending two.

Somebody already in the workspace is refused with member_is_owner (the closest existing code). Change what an existing member may do with PATCH /members/{userId} and the address and domain grant calls, which only work on people already in.

invitedBy is left null deliberately. The column records which PERSON invited somebody, and a key is not a person.

Remember which axis this sets. A role does not reach an address, and the addresses do not widen the role. The one exception is a role holding addresses:all, which reaches every address with no ids at all.

The authority of a key is, in the same way, its own scopes intersected with the role it was issued under, so a role holding a permission the key lacks is refused with insufficient_authority, a 403. No key or token holds a console-only permission, so a role with one of those in it, addresses:all included, is handed out in the app.

Requires the members:write scope.

Read off the same union the list computes, rather than by a query of its own. A member is the union of two populations (a membership row and a set of address grants, either of which exists perfectly well without the other), and a single-row lookup would be a second implementation of that union whose blind spot is precisely the legacy grant holders, who are most of the table today.

Requires the members:read scope.

Changes the role and nothing else, for somebody ALREADY in the workspace. It is also how a legacy grant holder stops being implied: they have address or domain grants and no membership row, this writes one, and from then on their permissions are what somebody chose rather than what their access happened to imply. Their grants are untouched.

A role holding a permission the key lacks is refused with insufficient_authority, a 403. No key or token holds a console-only permission, so moving somebody onto a role with addresses:all in it, which would reach every address for them without a single grant, is done in the app.

Addresses are deliberately not patchable from here. They are a set with a per-element access level, and an array on a PATCH would have to mean replace-whole: a silent mass revocation every time a client sends a list it read five minutes ago. The two address endpoints below move one at a time, so what happened is always what was asked for.

The owner role cannot be handed out. Making somebody an owner is a workspace transfer, which has entirely different consequences and is not an operation this API has.

Requires the members:write scope.

Takes somebody out of the workspace entirely: the membership row AND every address grant they hold here. Removing only the first would be the worst of both worlds. They would vanish from the list and go on reading the mail.

Idempotent, and it does NOT 404 on somebody who is not a member. The workspace owner is the one id it refuses, with 422 member_is_owner. That is not laxness about ids: the population this endpoint most needs to reach is the legacy grant holders, who have address grants and no membership row at all, so a pre-flight existence check would refuse exactly the people whose access most wants revoking. addressesRevoked reports what actually happened.

It does not touch their account, their sent mail or anything they wrote. It removes their access to this workspace.

Requires the members:write scope.

Hands one person one address, or changes what they may do with one they already have. An upsert: there is one row per address-and-person pair, so re-posting with a different access promotes a viewer to a member rather than adding a second grant.

A POST to the sub-collection rather than a PUT on the pair, because the row has no id a caller ever names.

This is the SECOND axis and it cannot widen the first: access: "member" on somebody whose role lacks emails:send does not let them send, it lets them read. Both have to agree before a message goes out.

Gated on members:write rather than on owning the address, which is where it differs from the older sharing path in the console. Ownership is the right gate for the person who put the domain in and the wrong one for an admin who owns nothing and is running the workspace access on behalf of the owner. Both write the same row.

The whole member comes back rather than the grant alone, so a client can re-render the row it is looking at without a second request, and so the answer reads the same whether the grant was new or an amendment.

Requires the members:write scope.

Takes one address back and leaves the person in the workspace, with their role and their other addresses. The narrow revocation, and the one to reach for when somebody moves team.

An address that is not on this workspace is refused rather than quietly ignored: a typo in the id reporting a successful revocation that never happened is the exact failure this endpoint exists to prevent.

The member comes back rather than a tombstone, because the interesting answer is what they can still reach. A { deleted: true } here would leave a client to work that out by subtraction.

Requires the members:write scope.

The invitations to this workspace that are still waiting, by email: the role and the addresses and whole domains each will grant once accepted, when it expires, and whether the last email reached them. A page at a time: follow nextCursor while hasMore is true.

A waiting invitation grants nothing. It becomes access only at the moment somebody accepts it, which is why it is listed here rather than in GET /members. An expired one stays on this list with expired: true until it is sent again or withdrawn.

A key limited to particular addresses or domains lists only the invitations that grant nothing outside them.

Requires the members:read scope.

Withdraws an invitation nobody has accepted. Its link stops working at once and nothing it would have granted is granted. Inviting the same address later with POST /members sends a new one.

A key limited to particular addresses or domains can withdraw only an invitation that grants nothing outside them. Any other answers 404.

Requires the members:write scope.

Sends a waiting invitation again: a new link, fourteen more days, and the old link retired, so only the newest email works. It renews an expired invitation too. delivered and deliveryError describe this send.

The per-person daily allowance is counted against the person who sent the invitation first when a key asks, and against the person an app acts for when an app does.

The invitation's role cannot hold more than the caller does, the same rule as POST /members: a role with a permission the key or token lacks, any console-only one included, is insufficient_authority, a 403. An app acting for a member is also refused with insufficient_authority when the invitation carries addresses or domains that member does not reach.

Requires the members:write scope.

Hands one person a whole domain: every address on it, including addresses added after the grant. An upsert, like POST /members/{userId}/addresses: posting again with a different access changes the grant rather than adding a second one.

It is the address axis, so it cannot widen the role: access: "member" lets somebody send only if their role also holds emails:send. Somebody who is not in the workspace yet is refused, so invite them first, and the owner is refused because they already reach every domain. A key or an app limited to particular addresses or domains is refused, and an app acting for a member can only give a domain that member reaches. Adding people needs a plan with team access, so a workspace without it is refused with 403 plan_required.

Requires the members:write scope.

Takes a whole domain back and leaves the person in the workspace, with their role and their other grants. Addresses on the domain that were granted one by one stay granted. A domain that is not on this workspace is refused rather than quietly ignored, and the member comes back so the answer shows what they can still reach.

Requires the members:write scope.