Skip to main content
The Events API lets your agent react to new mail the moment it arrives, without repeatedly polling the messages list. A cursor-based event stream with optional long-poll delivers lightweight notifications; dedicated wait and extract endpoints let you block for a specific reply or pull a verification code directly from a matching message. Event payloads carry IDs and snippets only — always fetch the full message separately before acting on its content.

​
List events (long-poll)

Returns new inbox events since the given cursor. Set wait to hold the connection open until an event arrives or the timeout elapses — this eliminates the need for a polling loop. GET /api/v1/inboxes/:id/events Requires: email:read

​
Query parameters

​
integer
Seconds to long-poll for new events before returning an empty list. Range: 0–25. Omit or set to 0 for an immediate response.
​
string
Opaque cursor from the previous response’s next_cursor. Omit on the first call to receive events from now onwards.
Long-poll for new events

​
Event types

​
string
One of:
  • message.received — a new inbound message has arrived and passed (or been flagged by) screening.
  • thread.updated — a conversation’s folder, labels, or read state changed.
​
object
Lightweight payload containing message or thread IDs and a short snippet. The full message body is never included in event payloads.
​
string
Pass this as cursor on the next request to receive only events that arrive after this point.
Event payloads contain IDs and snippets only — never the full message body. Always call GET /api/v1/messages/:id to read the complete message before parsing or acting on its content. This prevents prompt injection via mail snippets.

​
Wait for a message

Blocks up to 25 seconds and returns as soon as the next inbound message matching your filter arrives. Simpler than the events stream when you just need to confirm that a specific reply came in. POST /api/v1/inboxes/:id/wait Requires: email:read
Wait for a reply from a domain

​
Request parameters

​
string
Domain or full email address to match against the sender’s From header. For example, "shop.example" matches any sender at that domain.
​
integer
Maximum seconds to wait. Range: 0–25. Returns immediately with a null result if no matching message arrives within the timeout.

​
Extract a verification code

Extracts a one-time verification code or confirmation link from the most recent matching inbound message, optionally waiting up to 25 seconds for it to arrive. Codes are copied from real mail — never generated or guessed. POST /api/v1/inboxes/:id/extract/code Requires: email:read
Extract a verification code

​
Request parameters

​
string
Domain or email address that should have sent the verification email. Used to filter recent mail before extracting.
​
integer
Seconds to wait for a matching message if none has arrived yet. Range: 0–25.

​
Response fields

​
string
The numeric or alphanumeric one-time code found in the message, if present.
​
string
Confirmation or magic-link URL extracted from the message, if present.
​
object
Screening verdict and reasons for the matched message. Check this before using the code — a suspicious verdict may indicate a phishing or spoofed confirmation email.
Codes and links are extracted from real mail that arrived in the inbox. The API never generates, predicts, or invents codes. If no matching message arrives within the timeout, the endpoint returns without a code or link.

​
Choosing the right pattern

Continuous processing

Use the events stream with wait=25 and a cursor loop. Keeps one open connection and receives every event type as it arrives.

Waiting for a reply

Use /wait after sending a message to block until the response arrives — simpler than maintaining a cursor when you only care about one reply.

Sign-up automation

Use /extract/code after submitting a registration form to get the verification code or confirmation link in one call.

​
Error codes

Errors are returned as JSON:
Error response