Skip to content
docs
Browse the docsAgent identities

Agents

Agent identities

An inbox, a strong password and an optional fictional persona for one sign-up, made in one call. Create, read, wait for the code, extend and delete over /v1 or the dna CLI.

An agent identity is everything a sign-up form asks for, made in one call: a fresh address, a generated password and, if you ask, a fictional person with a name, birthday, address and phone number. Your agent or test types them into the form, then reads the verification code the site sends. Identities need a Pro or Business plan.

ProBusiness
Live identities at once1050
New identities an hour3030
Longest wait in one call30 s120 s
PersonasYesYes

An identity's inbox counts towards your active inboxes and lives within the plan's longest inbox life (24 hours on Pro, 72 on Business). When it expires, the identity goes with it. Save anything you want to keep to the vault.

Create an identity

POST/v1/identitiesidentities:writePro and up

Every field is optional. ttlMinutes is 1 to 1440 (default 30). prefix starts the address and four random characters follow it. passwordLength is 8 to 64 (default 16). persona: true adds a fictional person; country and gender steer it.

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

Persona countries: US, UK, AU, CA, DE, FR, JP, BR, IN, ES, IT, NL, KR, MX, SE, PL and NZ. Names, cities and address formats follow the country. Every persona is made up; never use one to pass yourself off as a real person.

To give an inbox you already have a password, pass its inboxId instead: the identity takes that inbox's address and expiry. An inbox holds one identity at most.

Wait for the code

After your agent submits the form, ask for the code. The call waits up to timeout seconds (capped by the plan) for a message with a verification code or magic link and returns the best match, with every match it found in rawMatches. from keeps out other senders.

GET/v1/identities/{id}/codemessages:readPro and up
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/code?timeout=30&from=github.com" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
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 }]
}

type is code or link. With nothing in time the answer is found: false with value: null; call again. The identity code call looks at mail already in the inbox as well as new mail. /v1 ignores a pattern parameter here (a caller's regular expression could run for too long); the CLI's --pattern is applied locally to the matches.

To wait for any message, not just a code:

GET/v1/identities/{id}/waitmessages:readPro and up
CLI
dna wait "$IDENTITY_ID" --timeout 30 --json
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" } }

Only mail that arrives after the request starts counts. timeout defaults to 30. At most five waits may be open at once per credential; a sixth answers 429 with too_many_waits. Codes and waiting explains how codes are found.

Read the mail

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

The list holds the newest 50 messages with a 200 character snippet; one message has bodyText and bodyHtml. An expired identity answers 410.

CLI
dna messages "$IDENTITY_ID"
dna message "$IDENTITY_ID" "$MESSAGE_ID" --html

List, extend and delete

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

The list holds live identities with their passwords and personas; ?expired=true adds expired ones. One identity also has its messageCount.

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. Past it, the answer is 403 lifetime_limit_reached.

CLI
dna extend "$IDENTITY_ID" --ttl 120
dna extend "$IDENTITY_ID" --label "new-label"
DELETE/v1/identities/{id}identities:writePro and up

Deletes the identity, its inbox and every message. ?keepInbox=true deletes only the identity and leaves the inbox and its mail.

CLI
dna delete "$IDENTITY_ID"
dna delete "$IDENTITY_ID" --keep-inbox

Errors

Statuserror.codeMeans
403forbiddenIdentities or personas need Pro or Business
429limit_exceededEvery live identity your plan allows, or every active inbox, is in use
429resource_limit_exceeded30 new identities in the last hour
404not_foundNo such identity on this account, or an inboxId that is not yours
409conflictThe inboxId already has an identity
410inbox_expiredThe identity's inbox has expired

With MCP, the same calls are the create_identity and get_identity_code tools. Every endpoint is in the Identities reference.

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