Skip to content
docs
Browse the docsInboxes

Mail

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:

FreeProBusiness
Active inboxes31050
Lifetime when made10 minutes30 minutes1 hour
Extensions1 of 10 minutesUnlimited, 30 minutes eachUnlimited, 1 hour each
Longest life20 minutes24 hours72 hours
Custom namesNoYesYes, and reserved for you
Aliases per inboxNone525
ForwardingNoYesYes

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:

FieldWhat it does
customNameThe 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.
domainA domain from GET /v1/domains (Pro and Business). Free always gets the default.
templateIdA 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"}'
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:

Statuserror.codeWhy
403plan_limit_exceededYou already have the plan's number of active inboxes
429hourly_limit_exceededFree accounts make at most 5 inboxes an hour
403upgrade_requiredcustomName or domain on the Free plan
400invalid_nameThe custom name breaks the rules above
409name_takenSomeone else has the address, it is reserved, or it was used recently
400invalid_domainThe 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.

JSON
{ "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"
GET/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.

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}/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"

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"}'

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"}'
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}/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"

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