# API · wait_for_email

{/* // POST /v1/inboxes/{addr}/wait */}

The blocking receive primitive. The request stays open (long-poll, IMAP IDLE server-side) until a
matching message arrives or the timeout elapses, then returns it with the **OTP code and verification
link already extracted**.

## `POST /v1/inboxes/{addr}/wait`

### Request

```json
{
  "from": "no-reply@acme.test",   // optional — match sender (substring, case-insensitive)
  "subject": "verification",      // optional — match subject (substring, case-insensitive)
  "regex": "\\b\\d{6}\\b",        // optional — match the body
  "since": "2026-06-12T18:00:00Z",// optional — only newer messages (default: now)
  "timeout_seconds": 120          // optional — server-capped (default 120, max 300)
}
```

```bash frame="terminal"
curl -sS -X POST \
  "$POSTERN_API_BASE_URL/v1/inboxes/signup-agent%40x4p.mszazu.com/wait" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "no-reply@acme.test", "subject": "verification", "timeout_seconds": 120 }'
```

### Response `200` — matched

```json
{
  "timed_out": false,
  "message": {
    "id": "msg_8Tz",
    "thread_id": "thread_9aB",
    "from": "no-reply@acme.test",
    "subject": "Verify your email",
    "received_at": "2026-06-12T18:05:42Z"
  },
  "extracted": {
    "otp_code": "492013",
    "verification_link": "https://acme.test/verify?token=…",
    "credentials": null
  }
}
```

### Response `200` — timed out

```json
{ "timed_out": true, "message": null, "extracted": null }
```

A timeout is a normal `200`, not an error — the agent decides whether to retry, lengthen the wait, or
re-trigger the upstream sign-up.
**Set the client read timeout above timeout_seconds:** This endpoint long-polls. Your HTTP client (and any reverse proxy between you and the API) must
  allow a read timeout greater than `timeout_seconds`, or the connection will be cut before the email
  arrives. The SDK and MCP server handle this automatically.

## Extraction

| Field | Meaning |
|---|---|
| `otp_code` | The one-time code, if found. |
| `verification_link` | The first click-through verification URL, if found. |
| `credentials` | Username/password pairs, when present. |

## Next

- [Quickstart · wait_for_email](https://docs.agents.mszazu.com/quickstart/wait-for-email/) — the full flow.
- [MCP · wait_for_email](https://docs.agents.mszazu.com/mcp/wait-for-email/) — the tool form.
- [Messages & threads](https://docs.agents.mszazu.com/api/messages-and-threads/) — non-blocking reads.