Skip to content
docs
Browse the docsIdentities

API reference

Identities API

Agent identities: an inbox, a password and an optional persona for one sign-up. Every identities 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/identitiesList identities
POST /v1/identitiesCreate an identity
GET /v1/identities/{id}Get an identity
PATCH /v1/identities/{id}Extend or relabel an identity
DELETE /v1/identities/{id}Delete an identity
GET /v1/identities/{id}/messagesList an identity's messages
GET /v1/identities/{id}/messages/{messageId}Get an identity's message
GET /v1/identities/{id}/waitWait for an identity's next message
GET /v1/identities/{id}/codeGet the code sent to an identity

List identities

GET/v1/identitiesidentities:readPro and up

Live agent identities with their passwords (Pro and Business). expired=true includes expired ones.

Query parameters

NameTypeRequiredDescription
expiredbooleannoInclude identities whose inbox has expired.
curl "https://api.dissolve.email/v1/identities" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "identities": [
    {
      "id": "idn4Rk2PqT9wYc1Lm0ZxA",
      "email": "signup7f2k@dissolve.email",
      "password": "w8#Kq2!vLz9@pR4m",
      "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
      "label": "GitHub test account",
      "expiresAt": "2026-11-19T10:30:00.000Z",
      "expired": false,
      "createdAt": "2026-11-19T10:00:00.000Z",
      "persona": null
    }
  ]
}

Create an identity

POST/v1/identitiesidentities:writePro and up

Makes an inbox and a strong password for one sign-up, and with persona a fictional person (name, birthday, address) to fill in the form. The password comes back in the answer and stays readable with GET. Pro 10 live identities, Business 50; at most 30 new ones an hour.

Body (application/json)

NameTypeRequiredDescription
labelstringnoWhat it is for, such as GitHub test account. At most 100 characters.
ttlMinutesintegernoMinutes until it expires. Default 30. 1 to 1440.
prefixstringnoStart of the address (letters and digits); four random characters follow. At most 20 characters.
domainstringnoA domain from GET /v1/domains.
passwordLengthintegernoLength of the generated password. Default 16. 8 to 64.
personabooleannoAlso make a fictional person.
countrystringnoThe persona's country. One of US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL, NZ.
genderstringnoThe persona's gender. One of male, female.
inboxIdstringnoAttach the identity to an inbox you already own instead of making one.
curl -X POST "https://api.dissolve.email/v1/identities" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"GitHub test account","ttlMinutes":30,"persona":true,"country":"AU"}'

Response 201

JSON
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "email": "signup7f2k@dissolve.email",
  "password": "w8#Kq2!vLz9@pR4m",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "ttlMinutes": 30,
  "label": "GitHub test account",
  "persona": {
    "firstName": "Mia",
    "lastName": "Nguyen",
    "fullName": "Mia Nguyen",
    "gender": "female",
    "country": "AU",
    "username": "mia.nguyen84",
    "dateOfBirth": "1984-06-12",
    "address": {
      "street": "14 Wattle Street",
      "city": "Brisbane",
      "state": "QLD",
      "zip": "4000",
      "formatted": "14 Wattle Street, Brisbane QLD 4000"
    },
    "phone": "+61 412 555 019"
  }
}

Get an identity

GET/v1/identities/{id}identities:readPro and up

One identity with its password, persona and message count.

Path parameters

NameDescription
idThe identitie id.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "email": "signup7f2k@dissolve.email",
  "password": "w8#Kq2!vLz9@pR4m",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "label": "GitHub test account",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "expired": false,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "persona": null,
  "messageCount": 1
}

Extend or relabel an identity

PATCH/v1/identities/{id}identities:writePro and up

Sets the identity to expire ttlMinutes from now (default: the plan's extension time) and changes its label, within the plan's longest inbox life.

Path parameters

NameDescription
idThe identitie id.

Body (application/json)

NameTypeRequiredDescription
ttlMinutesintegernoMinutes from now until it expires. 1 to 1440.
labelstringnoA new label. At most 100 characters.
curl -X PATCH "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlMinutes":60}'

Response 200

JSON
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "expiresAt": "2026-11-19T11:05:00.000Z",
  "ttlMinutes": 60,
  "label": "GitHub test account"
}

Delete an identity

DELETE/v1/identities/{id}identities:writePro and up

Deletes the identity and its inbox with every message. keepInbox=true deletes only the identity.

Path parameters

NameDescription
idThe identitie id.

Query parameters

NameTypeRequiredDescription
keepInboxbooleannoKeep the inbox and its mail.
curl -X DELETE "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "deleted": true
}

List an identity's messages

GET/v1/identities/{id}/messagesmessages:readPro and up

The newest 50 messages with a 200 character snippet each.

Path parameters

NameDescription
idThe identitie id.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "messages": [
    {
      "id": "Qm8wZ1kX0pLr7aYtV3nBc",
      "from": "noreply@github.com",
      "fromName": "GitHub",
      "subject": "Your GitHub launch code",
      "snippet": "Here is your GitHub launch code: 482913",
      "receivedAt": "2026-11-19T10:02:11.000Z"
    }
  ]
}

Get an identity's message

GET/v1/identities/{id}/messages/{messageId}messages:readPro and up

One message with its text and HTML bodies.

Path parameters

NameDescription
idThe identitie id.
messageIdThe message id.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "id": "Qm8wZ1kX0pLr7aYtV3nBc",
  "from": "noreply@github.com",
  "fromName": "GitHub",
  "subject": "Your GitHub launch code",
  "bodyText": "Here is your GitHub launch code: 482913",
  "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
  "snippet": "Here is your GitHub launch code: 482913",
  "receivedAt": "2026-11-19T10:02:11.000Z"
}

Wait for an identity's next message

GET/v1/identities/{id}/waitmessages:readPro and up

Holds the request until a message arrives after it started, or timeout (default 30, capped by the plan) runs out.

Path parameters

NameDescription
idThe identitie id.

Query parameters

NameTypeRequiredDescription
timeoutintegernoSeconds to wait, capped by the plan (Pro 30, Business 120). Default 30. 1 to 300.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/wait?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "timedOut": false,
  "message": {
    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code",
    "snippet": "Here is your GitHub launch code: 482913",
    "receivedAt": "2026-11-19T10:02:11.000Z"
  }
}

Get the code sent to an identity

GET/v1/identities/{id}/codemessages:readPro and up

The first verification code or magic link in the identity's mail, waiting up to timeout seconds for one. from filters by sender on the server; a pattern parameter is ignored here (a caller's regular expression could take too long).

Path parameters

NameDescription
idThe identitie id.

Query parameters

NameTypeRequiredDescription
timeoutintegernoSeconds to wait, capped by the plan. Default 0. 0 to 300.
fromstringnoOnly messages whose sender address contains this text.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/code?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "found": true,
  "type": "code",
  "value": "482913",
  "confidence": 0.95,
  "source": {
    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code"
  },
  "rawMatches": [
    {
      "type": "code",
      "value": "482913",
      "confidence": 0.95
    }
  ]
}

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