# Inboxes

> Create disposable inboxes with random or custom addresses, list and read them, extend them before they expire, forward their mail and add aliases.

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

An inbox is one address that receives mail for a while and then deletes itself, with every message and attachment in it. Each inbox has an `id` (used in every call) and an `address` (what you give to the outside world). Inboxes only receive; nothing can be sent from them.

How long an inbox lives depends on your plan:

| | Free | Pro | Business |
|---|---|---|---|
| Active inboxes | 3 | 10 | 50 |
| Lifetime when made | 10 minutes | 30 minutes | 1 hour |
| Extensions | 1 of 10 minutes | Unlimited, 30 minutes each | Unlimited, 1 hour each |
| Longest life | 20 minutes | 24 hours | 72 hours |
| Custom names | No | Yes | Yes, and reserved for you |
| Aliases per inbox | None | 5 | 25 |
| Forwarding | No | Yes | Yes |

[Rate limits and plans](/rate-limits) has every limit.

## Create an inbox

`POST /v1/inboxes` (scope `inboxes:write`)

With no body the address is random, such as `k3v9q2xa@dissolve.email`. Every field is optional:

| Field | What it does |
|---|---|
| `customName` | The part before the @ (Pro and Business): 3 to 32 letters, digits, dots, hyphens and underscores, starting and ending with a letter or digit. Reserved names are refused. |
| `domain` | A domain from `GET /v1/domains` (Pro and Business). Free always gets the default. |
| `templateId` | A saved [template](/rules#templates): its domain and forwarding address are applied. |

```bash cURL
curl -X POST https://api.dissolve.email/v1/inboxes \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customName": "signup-test"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve();
const inbox = await client.v1.createInbox({ customName: 'signup-test' });
console.log(inbox.id, inbox.address, inbox.expiresAt);
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
inbox = requests.post(
    "https://api.dissolve.email/v1/inboxes",
    json={"customName": "signup-test"},
    headers=HEADERS,
).json()
```

```json
{
  "id": "V1StGXR8Z5jdHi6BmyT2k",
  "address": "signup-test@dissolve.email",
  "domain": "dissolve.email",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "customName": "signup-test",
  "isReserved": false,
  "forwardTo": null
}
```

The answers you may get instead:

| Status | `error.code` | Why |
|---|---|---|
| 403 | `plan_limit_exceeded` | You already have the plan's number of active inboxes |
| 429 | `hourly_limit_exceeded` | Free accounts make at most 5 inboxes an hour |
| 403 | `upgrade_required` | `customName` or `domain` on the Free plan |
| 400 | `invalid_name` | The custom name breaks the rules above |
| 409 | `name_taken` | Someone else has the address, it is reserved, or it was used recently |
| 400 | `invalid_domain` | The domain is not offered for new inboxes |

On Business, a custom name is reserved for your account: when the inbox goes, the name is held for you for 45 days, so you can make it again. A name released by anyone else is held back for a while before another account can take it.

### Domains

`GET /v1/domains`

Lists the domains a new inbox can use and marks the default. Needs no scope.

```json
{ "domains": [{ "id": "d-0", "domain": "dissolve.email", "isDefault": true }], "defaultDomain": "dissolve.email" }
```

## List and read inboxes

`GET /v1/inboxes` (scope `inboxes:read`)

Every inbox on the account that has not expired, newest first.

```bash cURL
curl https://api.dissolve.email/v1/inboxes \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const inboxes = await client.v1.listInboxes();
```

```python Python
inboxes = requests.get("https://api.dissolve.email/v1/inboxes", headers=HEADERS).json()
```

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

One inbox with what you can do with it now: `canExtend`, `extendAvailableAt` (when the next extension opens), `lifetimeReached`, `forwardTo` (shown to the owner only) and `role`. `role` is `owner`, or `member` for an inbox a [team](/teams) shares with you. An expired inbox answers `410 gone`; one that is not yours answers `404 not_found`.

```json
{
  "id": "V1StGXR8Z5jdHi6BmyT2k",
  "address": "signup-test@dissolve.email",
  "domain": "dissolve.email",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "extensionCount": 0,
  "maxExtensions": null,
  "canExtend": false,
  "extendAvailableAt": "2026-11-19T10:15:00.000Z",
  "extendCooldownActive": true,
  "lifetimeReached": false,
  "maxTotalLifetimeMinutes": 1440,
  "forwardTo": null,
  "canForward": true,
  "customName": "signup-test",
  "ownerTier": "pro",
  "role": "owner",
  "sharedWithTeamId": null
}
```

## Extend an inbox

`POST /v1/inboxes/{id}/extend` (scope `inboxes:write`)

Adds the plan's extension time from now. The rules:

- Free: one extension of 10 minutes.
- Pro: as many as you like, but only once the inbox has 15 minutes or less left, and never past 24 hours of life.
- Business: as many as you like, once it has 30 minutes or less left, and never past 72 hours.

Too early answers `429 extend_too_early` with `availableAt`; the end of the road answers `403 lifetime_limit_reached` or `403 extension_limit_reached`. Only the inbox's owner can extend it.

```bash cURL
curl -X POST https://api.dissolve.email/v1/inboxes/$INBOX_ID/extend \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const extended = await client.v1.extendInbox(inbox.id);
console.log(extended.expiresAt);
```

```python Python
extended = requests.post(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/extend", headers=HEADERS).json()
```

## Forward mail

`PATCH /v1/inboxes/{id}` (scope `inboxes:write`)

Sends a copy of every new message to a real address (Pro and Business, owner only). Send `null` to stop. Addresses on dissolve.email and on known disposable services are refused with `400 invalid_forward_target`.

```bash cURL
curl -X PATCH https://api.dissolve.email/v1/inboxes/$INBOX_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"forwardTo": "me@example.com"}'
```

```ts TypeScript
await client.v1.updateInbox(inbox.id, { forwardTo: 'me@example.com' });
```

```python Python
requests.patch(
    f"https://api.dissolve.email/v1/inboxes/{inbox['id']}",
    json={"forwardTo": "me@example.com"},
    headers=HEADERS,
)
```

For forwarding only some mail, use a [forward rule](/rules).

## Aliases

An alias is another address on the inbox's domain that delivers into the same inbox. Pro allows 5 per inbox and Business 25; only the owner adds or removes them.

`POST /v1/inboxes/{id}/aliases` (scope `inboxes:write`)

```bash cURL
curl -X POST https://api.dissolve.email/v1/inboxes/$INBOX_ID/aliases \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias": "billing"}'
```

```ts TypeScript
const alias = await client.v1.createAlias(inbox.id, { alias: 'billing' });
```

```python Python
alias = requests.post(
    f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/aliases",
    json={"alias": "billing"},
    headers=HEADERS,
).json()
```

```json
{
  "id": "als6Rb1TnW8qXk3Zm5PcV",
  "aliasAddress": "billing@dissolve.email",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "createdAt": "2026-11-19T10:01:00.000Z",
  "message": "Alias billing@dissolve.email created. Mail to it lands in this inbox."
}
```

`alias` is lower case letters, digits and inner hyphens, at most 50 characters. A taken address answers `409 alias_taken`.

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

`DELETE /v1/inboxes/{id}/aliases/{aliasId}` (scope `inboxes:write`)

## Delete an inbox

`DELETE /v1/inboxes/{id}` (scope `inboxes:write`)

Deletes the inbox, its messages, attachments and aliases now. Only the owner can. Expired inboxes are deleted for you, so this is only for going early.

```bash cURL
curl -X DELETE https://api.dissolve.email/v1/inboxes/$INBOX_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
await client.v1.deleteInbox(inbox.id);
```

```python Python
requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}", headers=HEADERS)
```

> [!NOTE] Scopes
> Reading inboxes needs `inboxes:read`; creating, extending, forwarding, aliasing and deleting need `inboxes:write`. API keys have both. See [Authentication](/authentication#scopes).

Next: [read the mail](/messages) in an inbox, or [wait for a code](/verification).
