Poll a single verification wait
Fetches one verification wait by waitId so you can poll for its outcome instead of, or alongside, the webhook event.
Fetches one verification wait by waitId so you can poll for its outcome instead of, or alongside, the webhook event. While status is pending the resolution fields are null; once it flips to resolved, result holds the extracted value and from, messageId, and resolvedAt identify the message that satisfied it. A wait that lapsed past expiresAt reads expired with expiredAt set, while one you canceled reads canceled with canceledAt set — so you can tell a deadline lapse from a deliberate cancel. The {inbox} segment accepts the inbox UUID or full address; a waitId that does not belong to that inbox returns 404.
Scope: inboxes:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
inbox | string | yes | Inbox UUID or full address (e.g. agent@dairo.app). |
waitId | string (uuid) | yes | Verification wait id returned by the register call. |
Response
200 Success. Body: application/json, VerificationWait.
| Field | Type | Required | Description |
|---|---|---|---|
waitId | string (uuid) | yes | |
inboxId | string (uuid) | yes | |
agentId | string (uuid) or null | no | The Agent Passport that registered this wait, when the API key was agent-bound. |
status | "pending", "resolved", "expired" | yes | |
fromHint | string or null | no | |
instruction | string or null | no | The natural-language matcher instruction this wait was registered with. |
result | string or null | no | The value the AI matcher extracted per the instruction (present once resolved) — a code, a link, or a quoted line. |
from | string or null | no | The From address of the message that resolved the wait. |
messageId | string (uuid) or null | no | The inbound message that resolved the wait. |
idempotencyKey | string or null | no | |
expiresAt | string (date-time) | yes | |
createdAt | string (date-time) | yes | |
resolvedAt | string (date-time) or null | no | |
expiredAt | string (date-time) or null | no |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
409 | The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Register a durable verification wait on an inbox
Opens a durable background wait that watches the inbox's inbound mail and resolves the awaited email for you, returning immediately with status: pending.
Cancel a still-pending verification wait
Cancels a wait that is still pending, transitioning it to the terminal canceled status and stamping canceledAt; the response is the updated wait.