> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API — Inbox Notifications, Wait, and Code Extraction

> Cursor-based event stream with long-poll, wait-for-message blocking, and one-time code extraction for reactive agent email workflows.

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

<ParamField query="wait" type="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.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor from the previous response's `next_cursor`. Omit on the first call to receive events from now onwards.
</ParamField>

```bash title="Long-poll for new events" theme={null}
curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/events?wait=25&cursor=<cursor>" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

### Event types

<ResponseField name="type" type="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.
</ResponseField>

<ResponseField name="data" type="object">
  Lightweight payload containing message or thread IDs and a short snippet. The full message body is never included in event payloads.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Pass this as `cursor` on the next request to receive only events that arrive after this point.
</ResponseField>

<Warning>
  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.
</Warning>

***

## 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`

```bash title="Wait for a reply from a domain" theme={null}
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

<ParamField body="from" type="string">
  Domain or full email address to match against the sender's `From` header. For example, `"shop.example"` matches any sender at that domain.
</ParamField>

<ParamField body="timeout" type="integer">
  Maximum seconds to wait. Range: 0–25. Returns immediately with a `null` result if no matching message arrives within the timeout.
</ParamField>

***

## 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`

```bash title="Extract a verification code" theme={null}
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

<ParamField body="from" type="string">
  Domain or email address that should have sent the verification email. Used to filter recent mail before extracting.
</ParamField>

<ParamField body="wait" type="integer">
  Seconds to wait for a matching message if none has arrived yet. Range: 0–25.
</ParamField>

### Response fields

<ResponseField name="code" type="string">
  The numeric or alphanumeric one-time code found in the message, if present.
</ResponseField>

<ResponseField name="link" type="string">
  Confirmation or magic-link URL extracted from the message, if present.
</ResponseField>

<ResponseField name="screening" type="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.
</ResponseField>

<Note>
  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.
</Note>

***

## Choosing the right pattern

<CardGroup cols={3}>
  <Card title="Continuous processing" icon="rotate">
    Use the **events stream** with `wait=25` and a cursor loop. Keeps one open connection and receives every event type as it arrives.
  </Card>

  <Card title="Waiting for a reply" icon="hourglass">
    Use **`/wait`** after sending a message to block until the response arrives — simpler than maintaining a cursor when you only care about one reply.
  </Card>

  <Card title="Sign-up automation" icon="key">
    Use **`/extract/code`** after submitting a registration form to get the verification code or confirmation link in one call.
  </Card>
</CardGroup>

***

## Error codes

<Accordion title="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:

  ```json title="Error response" theme={null}
  {
    "error": {
      "code": "forbidden",
      "message": "The token does not have email:read.",
      "hint": "Re-issue the token with the email:read capability."
    }
  }
  ```
</Accordion>