# Inboxes API

> Disposable inboxes: create, read, extend, forward, delete. Every inboxes endpoint with its scope, parameters, body and an example answer.

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

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/inboxes` | [List inboxes](#list-inboxes) |
| `POST /v1/inboxes` | [Create an inbox](#create-an-inbox) |
| `GET /v1/inboxes/{id}` | [Get an inbox](#get-an-inbox) |
| `PATCH /v1/inboxes/{id}` | [Set or clear forwarding](#set-or-clear-forwarding) |
| `DELETE /v1/inboxes/{id}` | [Delete an inbox](#delete-an-inbox) |
| `POST /v1/inboxes/{id}/extend` | [Extend an inbox](#extend-an-inbox) |

### List 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
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listInboxes();
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/inboxes", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
[
  {
    "id": "V1StGXR8Z5jdHi6BmyT2k",
    "address": "k3v9q2xa@dissolve.email",
    "domain": "dissolve.email",
    "expiresAt": "2026-11-19T10:30:00.000Z",
    "createdAt": "2026-11-19T10:00:00.000Z",
    "customName": null
  }
]
```

### Create an inbox

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

Makes a disposable inbox that expires after the plan's lifetime (Free 10 minutes, Pro 30, Business 60). With no body the address is random. Counts against the plan's active inboxes and, on Free, five creations an hour.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `customName` | string | no | The local part to use, such as signup-test (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` | string | no | A domain from GET /v1/domains (Pro and Business). Omit for the default. |
| `templateId` | string | no | A template from GET /v1/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(); // reads DISSOLVE_API_KEY
const result = await client.v1.createInbox({
  customName: "signup-test"
});
```

```python Python
import os, requests

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

**Response** `200`

```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
}
```

### Get an inbox

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

One inbox with its expiry, whether it can be extended now, forwarding (owner only) and your role (`owner`, or `member` for an inbox a team shares with you). An expired inbox answers 410.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The inboxe id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getInbox(inboxId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

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

### Set or clear forwarding

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

Forwards every new message to a real address, or stops forwarding with null (Pro and Business, owner only). Addresses on dissolve.email and known disposable services are refused.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The inboxe id. |

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `forwardTo` | string or null | yes | Where to forward, or null to stop. |

```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
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateInbox(inboxId, {
  forwardTo: "me@example.com"
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/inboxes/{inbox_id}", json={
  "forwardTo": "me@example.com"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "V1StGXR8Z5jdHi6BmyT2k",
  "address": "k3v9q2xa@dissolve.email",
  "domain": "dissolve.email",
  "forwardTo": "me@example.com",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "message": "Emails will now be forwarded to me@example.com"
}
```

### Delete an inbox

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

Deletes the inbox, its messages, attachments and aliases now (owner only). A reserved name (Business) stays held for the plan's reservation days.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The inboxe id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteInbox(inboxId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "success": true
}
```

### Extend an inbox

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

Adds the plan's extension time (Free 10 minutes once; Pro 30 and Business 60, as often as you like). On Pro and Business an inbox can be extended only when it has 15 (Pro) or 30 (Business) minutes or less left, and never past the plan's longest life (24 hours on Pro, 72 on Business).

**Path parameters**

| Name | Description |
|---|---|
| `id` | The inboxe id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.extendInbox(inboxId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/extend", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "V1StGXR8Z5jdHi6BmyT2k",
  "address": "k3v9q2xa@dissolve.email",
  "domain": "dissolve.email",
  "expiresAt": "2026-11-19T11:00:00.000Z",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "extensionCount": 1,
  "maxExtensions": null,
  "canExtend": false,
  "extendAvailableAt": "2026-11-19T10:45:00.000Z",
  "extendCooldownActive": true
}
```
