Skip to content
docs
Browse the docsWaiting

API reference

Waiting API

Long-polls that answer when mail or a verification code arrives. Every waiting endpoint with its scope, parameters, body and an example answer.

Base URL https://api.dissolve.email. Send an API key or OAuth access token as Authorization: Bearer <token> (Authentication); an OAuth token needs the scope on each endpoint. Errors follow one shape.

EndpointSummary
GET /v1/inboxes/{id}/waitWait for a message
GET /v1/inboxes/{id}/codeWait for a verification code

Wait for a message

GET/v1/inboxes/{id}/waitmessages:read

Holds the request until mail arrives after since (default: now) or timeout runs out, then answers with up to 20 message summaries. It sleeps on the inbox's event stream rather than polling. At most five waits may be open at once per credential.

Path parameters

NameDescription
idThe waiting id.

Query parameters

NameTypeRequiredDescription
timeoutintegernoSeconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300. Default 0. 0 to 300.
sincestringnoOnly messages received after this time. Defaults to the moment the request starts for wait, and to every message for code.
fromstringnoOnly messages whose sender address contains this text, such as github.com. At most 254 characters.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/wait?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

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

Wait for a verification code

GET/v1/inboxes/{id}/codemessages:read

As wait, but answers with the first verification code, one-time password or magic link found, with the message it came from. Without since it also looks at mail already in the inbox. found is false when nothing turned up in time.

Path parameters

NameDescription
idThe waiting id.

Query parameters

NameTypeRequiredDescription
timeoutintegernoSeconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300. Default 0. 0 to 300.
sincestringnoOnly messages received after this time. Defaults to the moment the request starts for wait, and to every message for code.
fromstringnoOnly messages whose sender address contains this text, such as github.com. At most 254 characters.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=30&from=github.com" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

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

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