Skip to content
docs
Browse the docsInboxes

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.

EndpointSummary
GET /v1/inboxesList inboxes
POST /v1/inboxesCreate 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}/extendExtend an inbox

List 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"

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/inboxesinboxes: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)

NameTypeRequiredDescription
customNamestringnoThe 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.
domainstringnoA domain from GET /v1/domains (Pro and Business). Omit for the default.
templateIdstringnoA 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"}'

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

NameDescription
idThe inboxe id.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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}inboxes:writePro and up

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

NameDescription
idThe inboxe id.

Body (application/json)

NameTypeRequiredDescription
forwardTostring or nullyesWhere 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"}'

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

NameDescription
idThe inboxe id.
curl -X DELETE "https://api.dissolve.email/v1/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "success": true
}

Extend an inbox

POST/v1/inboxes/{id}/extendinboxes: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

NameDescription
idThe inboxe id.
curl -X POST "https://api.dissolve.email/v1/inboxes/$INBOX_ID/extend" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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
}

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown