# 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.

Source: https://docs.dissolve.email/teams

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.

> [!NOTE] Managed in the app, read over the API
> Making teams, inviting people and sharing inboxes happen in the app at app.dissolve.email. Those routes take the signed-in session cookie only, never an API key or an OAuth token. An inbox shared with you is readable over `/v1` with your own credential, as below.

## 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.

`POST /api/teams/{id}/invite` (signed-in session)

The invited person sees and answers invitations in the app:

`GET /api/teams/invites` (signed-in session)

`POST /api/teams/invites/{inviteId}/accept` (signed-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.

| 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:

`GET /v1/inboxes/{id}/messages` (scope `messages:read`)

`GET /v1/inboxes/{id}/code` (scope `messages:read`)

```bash cURL
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=60" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
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 });
```

```python Python
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.

`GET /api/shared-inbox/{teamId}/{inboxId}/connect` (signed-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.

| 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:

`GET /api/shared-inbox/{teamId}/{inboxId}/presence` (signed-in session)

`GET /api/shared-inbox/{teamId}/{inboxId}/receipts` (signed-in session)

`GET /api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/readers` (signed-in session)

`POST /api/shared-inbox/{teamId}/{inboxId}/messages/{messageId}/read` (signed-in session)

New mail itself reaches readers through the inbox's live stream, described on [Messages and attachments](/messages).
