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.
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.
Wait for a message
GET/v1/inboxes/{id}/waitmessages: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 |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/wait?timeout=30" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"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);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(){
"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.
Wait for a code
GET/v1/inboxes/{id}/codemessages: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.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=30&from=github.com" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"const code = await client.v1.waitForCode(inboxId, { timeout: 30, from: 'github.com' });
if (code.found) console.log(code.type, code.value);code = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/code",
params={"timeout": 30, "from": "github.com"},
headers=HEADERS,
timeout=60,
).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.
For agent identities
An agent identity has the same two calls under its own id.
GET/v1/identities/{id}/waitmessages:readPro and up
Waits for the next message after the request starts. timeout defaults to 30, capped by your plan.
{ "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" } }/v1/identities/{id}/codemessages:readPro and up
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.
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/code?timeout=30&from=github.com" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"const result = await client.v1.waitForIdentityCode(identityId, { timeout: 30, from: 'github.com' });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})"result = requests.get(
f"https://api.dissolve.email/v1/identities/{identity_id}/code",
params={"timeout": 30, "from": "github.com"},
headers=HEADERS,
timeout=60,
).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
fromwith the site's domain. - On
found: false, check the address was typed into the form, then call again rather than raisingtimeoutpast your plan's cap. - Free plans check once per call: call a few times with a pause between, or upgrade for real waits.
The playbooks put these together for test suites and agents.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown