Skip to main content
POST
Register a durable verification wait on an inbox

Authorizations

Authorization
string
header
required

Dairo API key, e.g. dairo_test_... or dairo_live_...

Path Parameters

inbox
string
required

Inbox UUID or full address (e.g. agent@dairo.app).

Body

application/json
timeoutSec
integer
required

How long the wait stays open, 30..=1800 seconds. expiresAt = now + timeoutSec.

Required range: 30 <= x <= 1800
fromHint
string | null

Optional case-insensitive substring matched against the inbound From address (e.g. 'github.com'). Null/absent matches any sender.

Maximum string length: 255
instruction
string | null

Natural-language instruction for the AI matcher: which email to wait for and what to extract (e.g. 'wait for the Telnyx password-reset email and return the reset link'). An EU-resident model evaluates each inbound email against it and, on a match, resolves the wait with the extracted value in result. Absent defaults to extracting any verification/OTP/confirmation code.

Maximum string length: 2000
idempotencyKey
string | null

Optional idempotency key; a retried register with the same key returns the same wait.

Maximum string length: 255

Response

Success

A durable await_verification wait. status is pending until it resolves (a code was extracted from an inbound message) or expires (deadline passed / canceled). Resolution outputs (code, from, messageId, resolvedAt) are present only once resolved.

waitId
string<uuid>
required
inboxId
string<uuid>
required
status
enum<string>
required
Available options:
pending,
resolved,
expired
expiresAt
string<date-time>
required
createdAt
string<date-time>
required
agentId
string<uuid> | null

The Agent Passport that registered this wait, when the API key was agent-bound.

fromHint
string | null
instruction
string | null

The natural-language matcher instruction this wait was registered with.

result
string | null

The value the AI matcher extracted per the instruction (present once resolved) — a code, a link, or a quoted line.

code
string | null

Legacy alias of result, kept for OTP callers (present once resolved).

from
string | null

The From address of the message that resolved the wait.

messageId
string<uuid> | null

The inbound message that resolved the wait.

idempotencyKey
string | null
resolvedAt
string<date-time> | null
expiredAt
string<date-time> | null