openemail members

Resolves one page of the workspace's members, the owner first and the rest by email. Each row carries two axes that a client must not merge: role and permissions say what the person may do, and addresses and domains say what they may do it to, each with its own access. A whole domain reaches every address on it, including ones made later. A send needs both axes, so emails:send with nothing granted sends from nothing.

The one exception is addresses:all. When permissions holds it, the person 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. addresses and domains still list only the grants made to them directly, which they may have kept from before or been given since, or none at all. Read reach from permissions first, and from those two arrays only when it lacks addresses:all.

The list is a union of people with a membership row and people who only hold address or domain grants and no membership row. The second group comes back with implied: true, role.id null and createdAt null, and their role is inferred from their grants: Member if any grant has access: 'member', Viewer otherwise. Until someone calls update for them, widening their addresses silently widens what they may do.

The workspace owner is the FIRST row, marked isOwner: true, so an unshared workspace returns one member rather than an empty page. They hold every permission by definition, and add, update and remove refuse them with member_is_owner. Exclude isOwner when counting seats.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Resolves a single member with their role, resolved permissions and address grants. The lookup runs over the same union as list, so a legacy grant holder with no membership row is found here too, with implied: true.

The path takes the account id from list, not an email. An email can change on the account, and a stale one would point at the wrong person. The owner is not a member, so their account id answers 404 like any unknown one.

Sends an invitation to join the workspace. Whether or not the address already has an OpenEmail account, the answer is an invitation rather than a member: nobody is put into a workspace without accepting, and this method 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. Calling it again for the same address within ten minutes is refused with 409 invitation_too_soon; after that it refreshes the one outstanding invitation rather than sending a second.

Somebody already in the workspace is refused with 422 member_is_owner. Change what an existing member may do with update, grantAddress and revokeAddress, which only work on people already in.

Role and grants are separate axes. access applies to every id in --address-ids and --domain-ids, and it never widens the role: access: 'member' under a role without emails:send still cannot send. A role holding addresses:all reaches every address without any ids, and no key or access token can invite with one, because none of them holds that console-only permission.

Moves a member to a different role and changes nothing else, for somebody ALREADY in the workspace. Their address and domain grants are untouched, and grants cannot be patched here at all: grantAddress and revokeAddress change one grant at a time.

This 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 implied is false and their permissions come from a role someone chose rather than from what their access implied.

Nobody joins through update. An account that is not in the workspace is 422 member_not_found: invite them with add and they are in once they accept. The owner role cannot be handed out, which is 409 role_immutable, and the workspace owner cannot be given a role, which is 422 member_is_owner.

Takes somebody out of the workspace entirely: the membership row and every address grant they hold on it. Removing only the row would drop them from the list while they kept reading the mail, so both go together.

It does not 404 for somebody who is not a member. The people this most needs to reach are legacy grant holders with no membership row, so there is no existence check, and addressesRevoked reports what actually happened. Zero is the honest answer for a no-op.

Their account, their sent mail and anything they wrote are untouched. Only their access to this workspace ends.

Gives one person one address on this workspace, or changes the access they already have to it. It is an upsert: there is one grant per person and address, so posting again with a different access turns a viewer into a member rather than adding a second grant.

This is the address axis and it cannot widen the role. access: 'member' lets somebody send as the address only if their role also holds emails:send, and otherwise it lets them read.

Granting an address to an account with no membership row makes them appear in list as an implied member whose role is inferred from their grants, so call update as well if the role should be a decision. The whole member comes back, which lets a client redraw the row without another read.

Removes one address grant and leaves the person in the workspace with their role and their other addresses. This is the narrow revocation to use when somebody changes team.

An address id that is not on this workspace is refused with 422 member_not_found rather than ignored, so a typo cannot report a revocation that never happened. An address that is on the workspace but was never granted to this person is a silent no-op, and the member comes back unchanged.

The member is returned rather than a tombstone, because the useful answer is what they can still reach.

Gives one person every address on one domain of this workspace, including addresses added after the grant, or changes the access they already have to it. It is an upsert: there is one grant per person and domain, so calling it again with a different access turns a viewer into a member rather than adding a second grant.

This is the address axis and it cannot widen the role. access: 'member' lets somebody send from the domain only if their role also holds emails:send, and otherwise it lets them read.

The person has to be in the workspace already, so invite them with add first. The whole member comes back, with the grant in domains.

Removes one domain grant and leaves the person in the workspace with their role and their other grants. Addresses on that domain that were granted to them one by one stay granted.

A domain id that is not on this workspace is refused with 422 member_not_found rather than ignored, so a typo cannot report a revocation that never happened. A domain that is on the workspace but was never granted to this person is a silent no-op, and the member comes back unchanged.

The member is returned rather than a tombstone, because the useful answer is what they can still reach.

Resolves one page of the invitations to this workspace that are still waiting, by email: the role and the addresses and whole domains each one grants once accepted, when it expires, and whether the last email reached them.

A waiting invitation grants nothing. It becomes access only at the moment somebody accepts it, which is why it is listed apart from list. An expired one stays on the list with expired: true until it is sent again or withdrawn.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

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

Sends a waiting invitation again: a new link, fourteen more days, and the old link retired, so only the newest email works. It is Send again on the members screen, and it renews an expired invitation too.