Inboxes
Create disposable inboxes with random or custom addresses, list and read them, extend them before they expire, forward their mail and add aliases.
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 has every limit.
Create an inbox
POST/v1/inboxesinboxes: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: 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();
const inbox = await client.v1.createInbox({ customName: 'signup-test' });
console.log(inbox.id, inbox.address, inbox.expiresAt);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(){
"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/domainsAny connection
Lists the domains a new inbox can use and marks the default. Needs no scope.
{ "domains": [{ "id": "d-0", "domain": "dissolve.email", "isDefault": true }], "defaultDomain": "dissolve.email" }List and read inboxes
GET/v1/inboxesinboxes:read
Every inbox on the account that has not expired, newest first.
curl https://api.dissolve.email/v1/inboxes \
-H "Authorization: Bearer $DISSOLVE_API_KEY"const inboxes = await client.v1.listInboxes();inboxes = requests.get("https://api.dissolve.email/v1/inboxes", headers=HEADERS).json()/v1/inboxes/{id}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 shares with you. An expired inbox answers 410 gone; one that is not yours answers 404 not_found.
{
"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}/extendinboxes: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.
curl -X POST https://api.dissolve.email/v1/inboxes/$INBOX_ID/extend \
-H "Authorization: Bearer $DISSOLVE_API_KEY"const extended = await client.v1.extendInbox(inbox.id);
console.log(extended.expiresAt);extended = requests.post(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/extend", headers=HEADERS).json()Forward mail
PATCH/v1/inboxes/{id}inboxes:writePro and up
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.
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"}'await client.v1.updateInbox(inbox.id, { forwardTo: 'me@example.com' });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.
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}/aliasesinboxes:writePro and up
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"}'const alias = await client.v1.createAlias(inbox.id, { alias: 'billing' });alias = requests.post(
f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/aliases",
json={"alias": "billing"},
headers=HEADERS,
).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.
/v1/inboxes/{id}/aliasesinboxes:read
DELETE/v1/inboxes/{id}/aliases/{aliasId}inboxes:write
Delete an inbox
DELETE/v1/inboxes/{id}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.
curl -X DELETE https://api.dissolve.email/v1/inboxes/$INBOX_ID \
-H "Authorization: Bearer $DISSOLVE_API_KEY"await client.v1.deleteInbox(inbox.id);requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}", headers=HEADERS)Next: read the mail in an inbox, or wait for a code.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown