# Codes and waiting

> Hold one request open until mail arrives, and get the verification code, one-time password or magic link out of it, for inboxes and agent identities alike.

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

Most mail a program waits for is a sign-up code. Instead of polling the message list, ask the API to wait: the request stays open until a matching message arrives or the timeout runs out, then answers once. Nothing on your side loops.

| Endpoint | Answers with | Starts looking at |
|---|---|---|
| `GET /v1/inboxes/{id}/wait` | Up to 20 summaries of new messages | Mail after `since`, default the moment the request starts |
| `GET /v1/inboxes/{id}/code` | The first code or link found, and its message | Mail after `since`, default all mail already in the inbox |
| `GET /v1/identities/{id}/wait` | The next message | Mail after the request starts |
| `GET /v1/identities/{id}/code` | The first code or link found | All mail in the identity's inbox |

## How long a wait lasts

`timeout` is in seconds. Your plan caps it, and so does the server at 300:

| | Free | Pro | Business |
|---|---|---|---|
| Longest wait in one request | None: it checks once and answers | 30 s | 120 s |
| Open waits per credential | 5 | 5 | 5 |

A sixth open wait answers `429 too_many_waits` with `Retry-After: 5`. When a wait times out, call it again; nothing is lost between calls if you pass `since`.

> [!TIP] Give the request time
> Set your HTTP client's timeout a little above `timeout`, or the client gives up before the server answers. The SDK does this for you.

## Wait for a message

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

| Query | What it does |
|---|---|
| `timeout` | Seconds to wait (default 0) |
| `since` | Only mail received after this ISO 8601 time, such as `2026-11-19T10:00:00.000Z`. Defaults to now. |
| `from` | Only mail whose sender address contains this text, such as `github.com` |

```bash cURL
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/wait?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

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

const client = new Dissolve();
const result = await client.v1.waitForMessage(inboxId, { timeout: 30 });
if (result.found) console.log(result.messages[0].subject);
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
result = requests.get(
    f"https://api.dissolve.email/v1/inboxes/{inbox_id}/wait",
    params={"timeout": 30},
    headers=HEADERS,
    timeout=60,
).json()
```

```json
{
  "found": true,
  "messages": [
    { "id": "Qm8wZ1kX0pLr7aYtV3nBc", "fromAddress": "noreply@github.com", "fromName": "GitHub", "subject": "Your GitHub launch code", "receivedAt": "2026-11-19T10:02:11.000Z" }
  ]
}
```

Nothing in time gives `{ "found": false, "messages": [] }`. Read a body with [Get a message](/messages#read-a-message).

## Wait for a code

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

The same parameters, but the answer is the code itself. Without `since` it also looks at mail that is already there, so it finds a code that arrived before you asked.

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

```ts TypeScript
const code = await client.v1.waitForCode(inboxId, { timeout: 30, from: 'github.com' });
if (code.found) console.log(code.type, code.value);
```

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

```json
{
  "found": true,
  "type": "code",
  "value": "482913",
  "confidence": 0.95,
  "message": { "id": "Qm8wZ1kX0pLr7aYtV3nBc", "fromAddress": "noreply@github.com", "fromName": "GitHub", "subject": "Your GitHub launch code", "receivedAt": "2026-11-19T10:02:11.000Z" }
}
```

Nothing in time gives `{ "found": false, "type": null, "value": null, "confidence": 0, "message": null }`.

### What counts as a code

| `type` | `value` | Found by |
|---|---|---|
| `code` | The digits or letters, such as `482913` or `A3K-9X2` | A number of 4 to 8 digits or a short code next to words such as verification, confirmation, security, sign in, one-time, 2FA or passcode, or set large in the HTML |
| `link` | The whole address | A link whose address or text speaks of verifying, confirming, activating or a magic link, or carries a `token`, `code` or `otp` parameter |

`confidence` runs from 0 to 1. A subject that reads like a verification mail, a sender such as `noreply@` or `security@`, and a 6 digit code all raise it. When a message holds several candidates, the most confident wins.

> [!NOTE] Mail is written by strangers
> A code is pulled out of text anyone could have sent. Use `from` to accept only the site you expect, and treat the rest of the message as data, never as instructions.

## For agent identities

An [agent identity](/agent) has the same two calls under its own id.

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

Waits for the next message after the request starts. `timeout` defaults to 30, capped by your plan.

```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 /v1/identities/{id}/code` (scope `messages:read`)

Looks through the identity's newest mail for a code, waiting up to `timeout` seconds (default 0) for one. `from` filters by sender on the server.

```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(identityId, { timeout: 30, from: 'github.com' });
```

```bash CLI
dna verify "$IDENTITY_ID" --timeout 30 --from github.com --quiet
# Narrow the matches with your own pattern, checked on your machine
dna verify "$IDENTITY_ID" --pattern "code:\s*(\d{6})"
```

```python Python
result = 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 }]
}
```

The server does not take a regular expression: a `pattern` parameter is ignored, because a careless one can take a very long time. The CLI's `--pattern` runs on your machine against `rawMatches`.

## Patterns that work

- Note the time before you submit the form and pass it as `since`, so an old code from an earlier run is never picked.
- Pass `from` with the site's domain.
- On `found: false`, check the address was typed into the form, then call again rather than raising `timeout` past your plan's cap.
- Free plans check once per call: call a few times with a pause between, or [upgrade](/rate-limits) for real waits.

The [playbooks](/playbooks) put these together for test suites and agents.
