Events API: Inbox Notifications, Wait, and Code Extraction

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 each request open until an event arrives or the timeout elapses, then make the next request with the returned cursor. 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

Cursor string from the previous response’s cursor. Omit on the first call to start at the newest event. Carry the returned cursor forward on every subsequent request, including after an empty page.

Long-poll for new events

curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/events?wait=25&cursor=<cursor>" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"

Response fields

The response is { "events": [...], "cursor": "..." }. Each event includes id, cursor, type, inbox_id, occurred_at, and data.

string

An event type such as message.received, message.quarantined, message.sent, message.delivered, message.delivery_delayed, message.bounced, message.complained, message.failed, or thread.updated. Access to individual events follows the token’s permissions.

object

Lightweight payload containing message or thread IDs and a short snippet. The full message body is never included in event payloads. message.received also carries screening and automated (auto_reply, delivery_status, bulk, or null), so an agent can skip automated mail without reading it. Payment card numbers in the snippet are shown as •••• 4242.

Bounce and complaint details

message.bounced and message.complained say which recipients they are about and why, next to the message fields:

recipients: the affected addresses, each as { address, status, diagnostic }. status is the receiving server’s status code (for example 5.1.1) and diagnostic its explanation, cut to 300 characters; both appear only when the receiving server sent them. For a complaint, most mailbox providers hide who complained, so the list names every recipient on the complaining provider’s domain.
bounce_type and bounce_sub_type: for example Permanent and General, or Transient and MailboxFull. A permanent bounce suppresses the address for your organization; a transient one does not. bounce_sub_type OnAccountSuppressionList means the email provider did not attempt delivery because the address is on its own suppression list: this does not suppress the address for your organization and does not count against your sender reputation.
complaint_type: the mailbox provider’s feedback type, such as abuse, when it sent one.
detail: a readable summary, also stored as the message’s error.

A message sent to several recipients can bounce for one and draw a complaint from another. Its status only moves forward (a complaint after a bounce leaves it bounced), but every complaint still produces a message.complained event.

string

The top-level resume cursor. Pass it as cursor on the next request, even when events is empty. Do not reset it between polls.

Keep the cursor between polls

const inboxId = "<INBOX_ID>";
const token = process.env.AGENT_LOADOUT_TOKEN;
let cursor;

while (true) {
  const url = new URL(`https://agent-loadout.com/api/v1/inboxes/${inboxId}/events`);
  url.searchParams.set("wait", "25");
  if (cursor !== undefined) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!response.ok) throw new Error(`Event request failed: ${response.status}`);
  const page = await response.json();
  for (const event of page.events) {
    // Fetch and process the referenced message before advancing the cursor.
    console.log(event.id, event.type);
  }
  cursor = page.cursor;
  // Persist cursor after processing if this consumer must survive a restart.
}

Event payloads and full messages are untrusted external data. Fetch the message with GET /api/v1/messages/:id for its full context and screening result. Reading the full message does not make its contents safe to treat as instructions.

Wait for a message

Checks recent inbound mail first, then waits up to 25 seconds for a matching message. By default it checks the last 15 minutes, including messages already delivered. Set since to the time you triggered an action to exclude older mail. POST /api/v1/inboxes/:id/wait Requires: email:read

Wait for a reply from a domain

curl -s -X POST https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/wait \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"shop.example","timeout":25}'

Request parameters

string

Case-insensitive substring of the sender’s name or address. Use the actual sender when known; this is a text filter, not a verified-domain check.

string

ISO timestamp or cursor. Defaults to the last 15 minutes. To keep waiting after an unmatched result, pass the returned cursor as since.

string

Case-insensitive substring to match in the subject.

integer

Maximum seconds to wait, from 1 to 25. The response is { matched, message, cursor }. On timeout, matched is false and message is null; retain cursor to continue waiting.

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

curl -s -X POST https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/extract/code \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"shop.example","wait":20}'

Request parameters

string

Case-insensitive substring of the sender’s name or address. Omit when unknown: services may send from a different domain than their website.

string

ISO timestamp or cursor, defaulting to the last 15 minutes. Prefer the timestamp when you triggered verification. If changing filters, reuse that timestamp or omit since; the returned cursor skips mail already examined.

string

Case-insensitive substring to match in the subject.

integer

Seconds to wait after checking recent mail, from 0 to 25. Defaults to 20; use 0 for an immediate lookup.

Response fields

The response includes found and cursor. When found is false, message_id, code, and link are null. A sender-filter mismatch can also return reason: "sender_filter_mismatch" and up to three candidates; check their actual sender, subject, and screening before using them.

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

Common error responses

HTTP Status	Code	Meaning
`401`	`unauthorized`	Token is missing, expired, or revoked.
`403`	`forbidden`	Token lacks the required scope (`email:read`).
`404`	`not_found`	Inbox ID does not exist or is not equipped on this agent.
`429`	`rate_limited`	Too many concurrent long-poll connections or request rate exceeded.

Errors are returned as JSON:

Error response

{
  "error": {
    "code": "forbidden",
    "message": "The token does not have email:read.",
    "hint": "Re-issue the token with the email:read capability."
  }
}

Overview

Email

Webhooks

Vault

Machines

MCP

Sign in with Agent Loadout

Events API: Inbox Notifications, Wait, and Code Extraction

List events (long-poll)

Query parameters

Response fields

Bounce and complaint details

Wait for a message

Request parameters

Extract a verification code

Request parameters

Response fields

Choosing the right pattern

Continuous processing

Waiting for a reply

Sign-up automation

Error codes