API reference
Inboxes API
Disposable inboxes: create, read, extend, forward, delete. Every inboxes endpoint with its scope, parameters, body and an example answer.
Base URL https://api.dissolve.email. Send an API key or OAuth access token as Authorization: Bearer <token> (Authentication); an OAuth token needs the scope on each endpoint. Errors follow one shape.
| Endpoint | Summary |
|---|---|
GET /v1/inboxes | List inboxes |
POST /v1/inboxes | Create an inbox |
GET /v1/inboxes/{id} | Get an inbox |
PATCH /v1/inboxes/{id} | Set or clear forwarding |
DELETE /v1/inboxes/{id} | Delete an inbox |
POST /v1/inboxes/{id}/extend | Extend an inbox |
List inboxes
/v1/inboxesinboxes:readEvery inbox on the account that has not expired, newest first.
curl "https://api.dissolve.email/v1/inboxes" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listInboxes();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
[
{
"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
/v1/inboxesinboxes:writeMakes 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. |
curl -X POST "https://api.dissolve.email/v1/inboxes" \
-H "Authorization: Bearer $DISSOLVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"customName":"signup-test"}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createInbox({
customName: "signup-test"
});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
{
"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
/v1/inboxes/{id}inboxes:readOne 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. |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getInbox(inboxId);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
{
"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
/v1/inboxes/{id}inboxes:writePro and upForwards 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. |
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"}'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"
});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
{
"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
/v1/inboxes/{id}inboxes:writeDeletes 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. |
curl -X DELETE "https://api.dissolve.email/v1/inboxes/$INBOX_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteInbox(inboxId);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
{
"success": true
}Extend an inbox
/v1/inboxes/{id}/extendinboxes:writeAdds 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. |
curl -X POST "https://api.dissolve.email/v1/inboxes/$INBOX_ID/extend" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.extendInbox(inboxId);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
{
"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
}Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown