# 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.

Source: https://docs.dissolve.email/agent

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.

| | Pro | Business |
|---|---|---|
| Live identities at once | 10 | 50 |
| New identities an hour | 30 | 30 |
| Longest wait in one call | 30 s | 120 s |
| Personas | Yes | Yes |

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](/vault).

## Create an identity

`POST /v1/identities` (scope `identities:write`)

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.

```bash cURL
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"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve();
const identity = await client.v1.createIdentity({ label: 'GitHub test account', ttlMinutes: 30, persona: true, country: 'AU' });
console.log(identity.email, identity.password);
```

```bash CLI
dna create --label "GitHub test account" --ttl 30 --persona --country AU --json
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
identity = requests.post(
    "https://api.dissolve.email/v1/identities",
    json={"label": "GitHub test account", "ttlMinutes": 30, "persona": True, "country": "AU"},
    headers=HEADERS,
).json()
```

```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.

> [!NOTE] Passwords are kept, sealed
> The password is encrypted at rest with a key held apart from the database, and you can read it again with GET for as long as the identity lives. The answers carry `Cache-Control: no-store`.

## 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}/code` (scope `messages:read`)

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/code?timeout=30&from=github.com" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const result = await client.v1.waitForIdentityCode(identity.id, { timeout: 30, from: 'github.com' });
```

```bash CLI
dna verify "$IDENTITY_ID" --timeout 30 --from github.com --quiet
```

```python Python
code = requests.get(
    f"https://api.dissolve.email/v1/identities/{identity['id']}/code",
    params={"timeout": 30, "from": "github.com"},
    headers=HEADERS,
    timeout=60,
).json()
```

```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}/wait` (scope `messages:read`)

```bash 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](/verification) explains how codes are found.

## Read the mail

`GET /v1/identities/{id}/messages` (scope `messages:read`)

`GET /v1/identities/{id}/messages/{messageId}` (scope `messages:read`)

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

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

## List, extend and delete

`GET /v1/identities` (scope `identities:read`)

`GET /v1/identities/{id}` (scope `identities:read`)

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}` (scope `identities:write`)

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`.

```bash CLI
dna extend "$IDENTITY_ID" --ttl 120
dna extend "$IDENTITY_ID" --label "new-label"
```

`DELETE /v1/identities/{id}` (scope `identities:write`)

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

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

## Errors

| Status | `error.code` | Means |
|---|---|---|
| 403 | `forbidden` | Identities or personas need Pro or Business |
| 429 | `limit_exceeded` | Every live identity your plan allows, or every active inbox, is in use |
| 429 | `resource_limit_exceeded` | 30 new identities in the last hour |
| 404 | `not_found` | No such identity on this account, or an `inboxId` that is not yours |
| 409 | `conflict` | The `inboxId` already has an identity |
| 410 | `inbox_expired` | The identity's inbox has expired |

With MCP, the same calls are the [`create_identity`](/mcp/tools#create-identity) and [`get_identity_code`](/mcp/tools#get-identity-code) tools. Every endpoint is in the [Identities reference](/reference/identities).
