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.
| Endpoint | Summary |
|---|---|
GET /v1/inboxes/{id}/wait | Wait for a message |
GET /v1/inboxes/{id}/code | Wait for a verification code |
Wait for a message
/v1/inboxes/{id}/waitmessages:readHolds 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
| Name | Description |
|---|---|
id | The waiting id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | no | Seconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300. Default 0. 0 to 300. |
since | string | no | Only messages received after this time. Defaults to the moment the request starts for wait, and to every message for code. |
from | string | no | Only 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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForMessage(inboxId, { timeout: 30 });import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/wait", params={
"timeout": "30"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())Response 200
{
"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
/v1/inboxes/{id}/codemessages:readAs 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
| Name | Description |
|---|---|
id | The waiting id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | no | Seconds to wait. Capped by the plan's agentWaitTimeoutSeconds (Free 0, so it checks once) and by 300. Default 0. 0 to 300. |
since | string | no | Only messages received after this time. Defaults to the moment the request starts for wait, and to every message for code. |
from | string | no | Only 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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForCode(inboxId, { timeout: 30, from: 'github.com' });import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/code", params={
"timeout": "30",
"from": "github.com"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())Response 200
{
"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