Block until a matching message arrives (wait_for_email)

POST

/v1/inboxes/{inbox_id}/wait

• Production
• Local

The killer primitive. Blocks (IMAP poll) until the next matching message arrives in this inbox or the timeout elapses, returning the message plus an extracted OTP code / verification link.

Authorizations

• AgentKey
  mailbox:read

Parameters

Path Parameters

inbox_id

required

string

Opaque inbox id (the canonical path key). The inbox’s email address is also accepted here as a within-project alias. Treat the id as opaque.

Request Body

Block until a matching message arrives. The inbox is taken from the path on POST /v1/inboxes/{inbox_id}/wait; on the legacy POST /v1/wait it is the address field.

object

address

Required on POST /v1/wait; ignored on the inbox-scoped path.

string

from

Substring match on the From header.

string

subject

Substring match on the Subject header.

string

match

Regex matched over subject + body.

string

folder

string

link_hint

Hint to bias verification-link extraction.

string

timeout_seconds

Max seconds to block (default 300, capped at 600).

integer

since_now

When true (default), match only arrivals after the wait begins.

boolean

Responses

200

Matched or timed out.

object

timed_out

boolean

message

object

id

Opaque

string

Example

msg_8Tz

thread_id

string

Example

thr_9aB

inbox

string

Example

agent7@extrovertmail.com

direction

Derived relative to the owning inbox.

string

Allowed values: inbound outbound

from

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

to

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

cc

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

reply_to

Array<object>

A structured RFC5322 address.

object

name

string

Example

Acme Support

email

required

string format: email

Example

support@acme.test

subject

string

text

Decoded UTF-8 text/plain MIME alternative; null when the message had no plain-text part. Never derived from HTML.

string

nullable

html

Decoded text/html MIME alternative; null for text-only mail. Never synthesized from plain text.

string

nullable

extracted_text

Best-effort derivative of text with quoted history and signatures removed; null when text is absent or no authored text remains. Not authoritative.

string

nullable

extracted_html

Best-effort derivative of html with common quoted-history containers removed; null when html is absent or no authored HTML remains. Not authoritative.

string

nullable

date

Original Date header value.

string

message_id

RFC5322 Message-ID.

string

in_reply_to

RFC5322 In-Reply-To header.

string

references

RFC5322 References header chain.

string

folder

string

seen

Native IMAP \Seen flag (read state).

boolean

extracted

OTP code / verification link extracted from the matched message.

object

otp

string

nullable

link

string

nullable

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope