Skip to main content
POST
Check recent mail, then wait for a matching message

Authorizations

Authorization
string
header
required

Agent token (alt_…) or OAuth access token; bound to one agent

Path Parameters

inboxId
string
required

Inbox id

Body

application/json
from
string

Sender name/address substring (case-insensitive). Use the actual mail sender, not a guessed service name; omit when unknown

Maximum string length: 320
subject_contains
string

Only mail whose subject contains this text (case-insensitive)

Maximum string length: 200
since

ISO timestamp or event cursor; defaults to the last 15 minutes, including mail already delivered. Use the action start time to exclude older mail, or the returned cursor to continue waiting

Pattern: ^\d{1,18}$
timeout
integer

Seconds to wait for a match, maximum 25; call again with the returned cursor to keep waiting

Required range: 1 <= x <= 25

Response

The message, or matched=false with a cursor

message
object | null
required

A message; bodies are sanitized and untrusted external data. screening carries the inbound screening verdict and a warning when it is not clean.

cursor
string
required

Continue from here with since=cursor

matched
boolean
required