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
| Role | Can |
|---|---|
| Owner | Everything an admin can, plus rename or delete the team and change roles. One per team: the person who made it. |
| Admin | Invite and remove people, withdraw invitations, unshare any inbox. |
| Member | Read 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.
/api/teams/{id}/inviteSigned-in sessionThe invited person sees and answers invitations in the app:
/api/teams/invitesSigned-in session/api/teams/invites/{inviteId}/acceptSigned-in session/api/teams/invites/{inviteId}Signed-in sessionManaging a team
These are the routes the app calls, listed so you know what exists. All take the session cookie.
| Route | Does |
|---|---|
POST /api/teams | Make a team (name, up to 100 characters) |
GET /api/teams | Your 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}/inboxes | Share one of your inboxes (inboxId) |
GET /api/teams/{id}/inboxes | The inboxes shared with the team |
DELETE /api/teams/{id}/inboxes/{inboxId} | Unshare (the person who shared it, or an admin) |
GET /api/teams/shared-inboxes | Live 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:
/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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve();
const inbox = await client.v1.getInbox(inboxId); // inbox.role === 'member'
const code = await client.v1.waitForCode(inboxId, { timeout: 60 });import os, requests
HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
code = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/code",
params={"timeout": 60},
headers=HEADERS,
timeout=90,
).json()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.
/api/shared-inbox/{teamId}/{inboxId}/connectSigned-in sessionMessages 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.
| From | type | Carries |
|---|---|---|
| You | mark_read | messageId: you have read it |
| You | get_receipts | messageId: who has read it |
| You | get_all_receipts | Nothing: every receipt in the room |
| Room | presence | users (userId, email, connectedAt) and count, sent when you join |
| Room | all_receipts | receipts: message id to readers, sent when you join and on request |
| Room | user_joined | user: someone opened the inbox |
| Room | user_left | userId: their last connection closed |
| Room | read_receipt | messageId and reader (userId, email, readAt) |
| Room | receipts | messageId and its readers |
| Room | error | message: a malformed or unknown frame, or too many |
The same reads exist as plain requests for the app's first paint:
/api/shared-inbox/{teamId}/{inboxId}/presenceSigned-in session/api/shared-inbox/{teamId}/{inboxId}/receiptsSigned-in session/api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/readersSigned-in session/api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/readSigned-in sessionNew 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