Skip to content
docs
Browse the docsTeams and shared inboxes

Accounts and teams

Teams and shared inboxes

Share inboxes with a team on the Business plan, with roles, email invitations, live presence and read receipts. What the app does, and what the API can reach.

A team is a group of people who read the same inboxes. A QA lead makes the team, invites testers by email, and shares the inboxes the test runs use. Everyone sees new mail as it lands, who else is looking, and who has read what.

Teams are on the Business plan: up to 5 teams, each with up to 25 people (members and pending invitations together). The limits come from the team owner's plan, so invited people need no paid plan of their own.

Roles

RoleCan
OwnerEverything an admin can, plus rename or delete the team and change roles. One per team: the person who made it.
AdminInvite and remove people, withdraw invitations, unshare any inbox.
MemberRead every inbox shared with the team, share their own inboxes, leave.

Sharing never hands over an inbox. Only its owner can extend it, delete it, set forwarding or add aliases; team members read it. Removing a member also withdraws the inboxes they shared.

Invitations

An admin invites an address. The invitation is emailed and waits for 7 days, also for an address with no account yet: it shows up once that person signs up with it. An admin can send at most 20 invitations an hour.

POST/api/teams/{id}/inviteSigned-in session

The invited person sees and answers invitations in the app:

GET/api/teams/invitesSigned-in session
POST/api/teams/invites/{inviteId}/acceptSigned-in session
DELETE/api/teams/invites/{inviteId}Signed-in session

Managing a team

These are the routes the app calls, listed so you know what exists. All take the session cookie.

RouteDoes
POST /api/teamsMake a team (name, up to 100 characters)
GET /api/teamsYour teams, with your role and the member count
GET /api/teams/{id}One team, its members and, for admins, pending invitations
PATCH /api/teams/{id}Rename it
DELETE /api/teams/{id}Delete it (owner only)
DELETE /api/teams/{id}/invite/{email}Withdraw an invitation
PATCH /api/teams/{id}/members/{userId}Make someone admin or member (owner only)
DELETE /api/teams/{id}/members/{userId}Remove someone, or leave
POST /api/teams/{id}/inboxesShare one of your inboxes (inboxId)
GET /api/teams/{id}/inboxesThe inboxes shared with the team
DELETE /api/teams/{id}/inboxes/{inboxId}Unshare (the person who shared it, or an admin)
GET /api/teams/shared-inboxesLive inboxes other members share with you

Reading a shared inbox over the API

An inbox shared with you answers your own API key or OAuth token like one of yours, read only. Find its id in the app (or in GET /v1/inboxes/{id}, whose role is member for a shared inbox), then read it and wait on it:

GET/v1/inboxes/{id}/messagesmessages:read GET/v1/inboxes/{id}/codemessages:read
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=60" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Changing the inbox (extend, delete, forwarding, aliases) answers 403 with owner_only for a member. Labels you put on a shared inbox's messages are your own; other members do not see them.

Presence and read receipts

Each shared inbox has a live room in the app. Opening the inbox joins it over a WebSocket; the room says who else is there and who has read each message. It needs the inbox owner on Business and a signed-in session, and the room is closed to anyone not in the team the inbox is shared with.

GET/api/shared-inbox/{teamId}/{inboxId}/connectSigned-in session

Messages are JSON text frames of up to 1 KB, and a socket may send only a few a second (too many answer error). One connection per person: a new tab replaces the old one.

FromtypeCarries
Youmark_readmessageId: you have read it
Youget_receiptsmessageId: who has read it
Youget_all_receiptsNothing: every receipt in the room
Roompresenceusers (userId, email, connectedAt) and count, sent when you join
Roomall_receiptsreceipts: message id to readers, sent when you join and on request
Roomuser_joineduser: someone opened the inbox
Roomuser_leftuserId: their last connection closed
Roomread_receiptmessageId and reader (userId, email, readAt)
RoomreceiptsmessageId and its readers
Roomerrormessage: a malformed or unknown frame, or too many

The same reads exist as plain requests for the app's first paint:

GET/api/shared-inbox/{teamId}/{inboxId}/presenceSigned-in session
GET/api/shared-inbox/{teamId}/{inboxId}/receiptsSigned-in session
GET/api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/readersSigned-in session
POST/api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/readSigned-in session

New mail itself reaches readers through the inbox's live stream, described on Messages and attachments.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown