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.
| Endpoint | Summary |
|---|---|
GET /v1/identities | List identities |
POST /v1/identities | Create 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}/messages | List an identity's messages |
GET /v1/identities/{id}/messages/{messageId} | Get an identity's message |
GET /v1/identities/{id}/wait | Wait for an identity's next message |
GET /v1/identities/{id}/code | Get the code sent to an identity |
List identities
/v1/identitiesidentities:readPro and upLive agent identities with their passwords (Pro and Business). expired=true includes expired ones.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
expired | boolean | no | Include identities whose inbox has expired. |
curl "https://api.dissolve.email/v1/identities" \
-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.listIdentities();dna list --jsonimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/identities", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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
/v1/identitiesidentities:writePro and upMakes 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)
| Name | Type | Required | Description |
|---|---|---|---|
label | string | no | What it is for, such as GitHub test account. At most 100 characters. |
ttlMinutes | integer | no | Minutes until it expires. Default 30. 1 to 1440. |
prefix | string | no | Start of the address (letters and digits); four random characters follow. At most 20 characters. |
domain | string | no | A domain from GET /v1/domains. |
passwordLength | integer | no | Length of the generated password. Default 16. 8 to 64. |
persona | boolean | no | Also make a fictional person. |
country | string | no | The persona's country. One of US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL, NZ. |
gender | string | no | The persona's gender. One of male, female. |
inboxId | string | no | Attach 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"}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createIdentity({
label: "GitHub test account",
ttlMinutes: 30,
persona: true,
country: "AU"
});dna create --label "GitHub test account" --ttl 30 --persona --country AU --jsonimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/identities", json={
"label": "GitHub test account",
"ttlMinutes": 30,
"persona": True,
"country": "AU"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 201
{
"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
/v1/identities/{id}identities:readPro and upOne identity with its password, persona and message count.
Path parameters
| Name | Description |
|---|---|
id | The identitie id. |
curl "https://api.dissolve.email/v1/identities/$IDENTITY_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.getIdentity(identityId);dna get "$IDENTITY_ID" --jsonimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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
/v1/identities/{id}identities:writePro and upSets 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
| Name | Description |
|---|---|
id | The identitie id. |
Body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
ttlMinutes | integer | no | Minutes from now until it expires. 1 to 1440. |
label | string | no | A 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}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateIdentity(identityId, {
ttlMinutes: 60
});dna extend "$IDENTITY_ID" --ttl 60import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/identities/{identity_id}", json={
"ttlMinutes": 60
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"id": "idn4Rk2PqT9wYc1Lm0ZxA",
"expiresAt": "2026-11-19T11:05:00.000Z",
"ttlMinutes": 60,
"label": "GitHub test account"
}Delete an identity
/v1/identities/{id}identities:writePro and upDeletes the identity and its inbox with every message. keepInbox=true deletes only the identity.
Path parameters
| Name | Description |
|---|---|
id | The identitie id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
keepInbox | boolean | no | Keep the inbox and its mail. |
curl -X DELETE "https://api.dissolve.email/v1/identities/$IDENTITY_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.deleteIdentity(identityId);dna delete "$IDENTITY_ID"import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/identities/{identity_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"deleted": true
}List an identity's messages
/v1/identities/{id}/messagesmessages:readPro and upThe newest 50 messages with a 200 character snippet each.
Path parameters
| Name | Description |
|---|---|
id | The identitie id. |
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages" \
-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.listIdentityMessages(identityId);dna messages "$IDENTITY_ID" --jsonimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/messages", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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
/v1/identities/{id}/messages/{messageId}messages:readPro and upOne message with its text and HTML bodies.
Path parameters
| Name | Description |
|---|---|
id | The identitie id. |
messageId | The message id. |
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages/$MESSAGE_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.getIdentityMessage(identityId, messageId);dna message "$IDENTITY_ID" "$MESSAGE_ID"import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/messages/{message_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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
/v1/identities/{id}/waitmessages:readPro and upHolds the request until a message arrives after it started, or timeout (default 30, capped by the plan) runs out.
Path parameters
| Name | Description |
|---|---|
id | The identitie id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | no | Seconds 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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForIdentityMessage(identityId, { timeout: 30 });dna wait "$IDENTITY_ID" --timeout 30 --jsonimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/wait", params={
"timeout": "30"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())Response 200
{
"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
/v1/identities/{id}/codemessages:readPro and upThe 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
| Name | Description |
|---|---|
id | The identitie id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | no | Seconds to wait, capped by the plan. Default 0. 0 to 300. |
from | string | no | Only 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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForIdentityCode(identityId, { timeout: 30 });dna verify "$IDENTITY_ID" --timeout 30 --quietimport os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/code", params={
"timeout": "30"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())Response 200
{
"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