# 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.

Source: https://docs.dissolve.email/reference/waiting

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

| Endpoint | Summary |
|---|---|
| `GET /v1/inboxes/{id}/wait` | [Wait for a message](#wait-for-a-message) |
| `GET /v1/inboxes/{id}/code` | [Wait for a verification code](#wait-for-a-verification-code) |

### Wait for a message

`GET /v1/inboxes/{id}/wait` (scope `messages: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**

| 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. |

```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(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForMessage(inboxId, { timeout: 30 });
```

```python Python
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`

```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}/code` (scope `messages: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**

| 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. |

```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
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' });
```

```python Python
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`

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