Skip to content
docs
Browse the docsCodes and waiting

Mail

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.

EndpointAnswers withStarts looking at
GET /v1/inboxes/{id}/waitUp to 20 summaries of new messagesMail after since, default the moment the request starts
GET /v1/inboxes/{id}/codeThe first code or link found, and its messageMail after since, default all mail already in the inbox
GET /v1/identities/{id}/waitThe next messageMail after the request starts
GET /v1/identities/{id}/codeThe first code or link foundAll 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:

FreeProBusiness
Longest wait in one requestNone: it checks once and answers30 s120 s
Open waits per credential555

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
QueryWhat it does
timeoutSeconds to wait (default 0)
sinceOnly mail received after this ISO 8601 time, such as 2026-11-19T10:00:00.000Z. Defaults to now.
fromOnly 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"
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"
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

typevalueFound by
codeThe digits or letters, such as 482913 or A3K-9X2A 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
linkThe whole addressA 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.

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