Wait for the next message in an inbox
Requires a full key or an inbox key (bound inbox only). Returns the first matching message, or 204 when timeout seconds pass. after is a message id or a list cursor. Omit after to wait for a message received after this request starts. from is an exact sender address, ignoring case. subject_contains is a literal subject substring, ignoring case. The body is message metadata. Message bodies are not included. A missing, deleted, other-tenant or other-mode inbox is not found. Concurrent waits are limited per process and per tenant. A full limit returns 429. Messages and cursors are ordered by received_at and id, oldest matching first. received_at is the original mail receive time, not the time storage completes. A late retried delivery can arrive after a newer message while retaining an earlier received_at. It can fall before an advanced cursor or the request start time and will then be skipped. To reconcile retained messages, list messages again without a cursor and deduplicate by message id.
Path parameters
| Parameter | Description |
|---|---|
inbox_idrequiredstring |
Query parameters
| Parameter | Description |
|---|---|
afterstring | A message id or a next_cursor value. Absent waits for a message received after the request starts. |
timeoutinteger | Seconds to wait before returning 204. |
fromstring | Sender address. The match is exact and ignores case. |
subject_containsstring | Literal subject substring. The match ignores case. |
Full parameter schemas and constraints
inbox_id*stringafter?stringA message id or a next_cursor value. Absent waits for a message received after the request starts.
timeout?integerSeconds to wait before returning 204.
1 <= value <= 3030from?stringSender address. The match is exact and ignores case.
subject_contains?stringLiteral subject substring. The match ignores case.
bearerAuthAuthorizationBearer <token>API key: st_live_... or st_test_...
The first matching message, without bodies.
application/json- response
id*stringinbox_id*stringthread_id*stringdirection*string"inbound""outbound"from*to*array<string>cc*array<string>subject*stringpreview*stringlength <= 200size_bytes*integerint64attachments*array<>received_at*stringdate-timeexpires_at*stringdate-timeauthentication*extracted*