Register a durable verification wait on an inbox

POST https://api.dairo.app/v1/inboxes/{inbox}/verification-waits

Opens a durable background wait that watches the inbox's inbound mail and resolves the awaited email for you, returning immediately with status: pending. An EU-resident AI matcher evaluates each incoming message against your natural-language instruction — for example wait for the GitHub sign-in code and return it — and, on a match, resolves the wait with the extracted value in result (a code, a link, or a quoted line); omit instruction and it defaults to matching any verification, OTP, or confirmation code. Set fromHint to the sender's address (matched exactly) or domain (which also matches its subdomains) — anything else is a 400 — so only that sender, authenticated by DMARC, can resolve the wait (a wait without a hint resolves from any sender except one that failed its domain's DMARC policy); and timeoutSec (30–1800 seconds, default 300) to size the window, where expiresAt is now + timeoutSec. The outcome later arrives as a verification.resolved (carrying result, from, and messageId) or verification.expired event on your webhook and the durable event ledger, or by polling the wait. Pass idempotencyKey to make retries safe — a repeat with the same key returns the original wait, scoped to this inbox, without opening a second one. An inbox allows at most 50 open waits at once; registering beyond that returns 429, and an unknown or non-owned {inbox} returns 404.

Scope: inboxes:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/inboxes/support/verification-waits" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeoutSec": 30
  }'

Path parameters

Body

Required, application/json: RegisterVerificationWaitRequest.

Response

200 Success. Body: application/json, VerificationWait.

{
  "waitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "fromHint": null,
  "instruction": null,
  "result": null,
  "from": null,
  "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "idempotencyKey": null,
  "expiresAt": "2026-10-19T09:30:00Z",
  "createdAt": "2026-10-19T09:30:00Z",
  "resolvedAt": "2026-10-19T09:30:00Z",
  "expiredAt": "2026-10-19T09:30:00Z"
}

201 Created. Body: application/json, VerificationWait.

{
  "waitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "inboxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "fromHint": null,
  "instruction": null,
  "result": null,
  "from": null,
  "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "idempotencyKey": null,
  "expiresAt": "2026-10-19T09:30:00Z",
  "createdAt": "2026-10-19T09:30:00Z",
  "resolvedAt": "2026-10-19T09:30:00Z",
  "expiredAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.