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

# Inboxes API — List, Create, and Configure Agent Inboxes

> List and create agent inboxes, pull per-folder unread counts, and configure sender allow/block rules to control which mail the agent receives.

Every agent can carry one or more dedicated email addresses called inboxes. The Inboxes API lets you list the inboxes already equipped on a token's agent, provision a brand-new agent with its own inbox in a single call using an organization key, pull per-folder unread counts, and manage sender rules that control which mail reaches the agent at all.

***

## List inboxes

Returns all inboxes equipped on the agent identified by the bearer token. Each entry includes the stable ID you pass to message and thread endpoints.

**`GET /api/v1/inboxes`**

Requires: `email:read`

```bash title="List inboxes" theme={null}
curl -s https://agent-loadout.com/api/v1/inboxes \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

### Response fields

<ResponseField name="id" type="string">
  Stable inbox identifier (prefix `inb_`). Pass this to messages, threads, events, and other inbox-scoped endpoints.
</ResponseField>

<ResponseField name="address" type="string">
  The full email address assigned to this inbox (e.g. `support@agents.example.com`).
</ResponseField>

<ResponseField name="display_name" type="string">
  Human-readable label shown in the dashboard and used as the sender display name.
</ResponseField>

***

## Create an agent with an inbox

Provisions a new agent and attaches a ready inbox in one call. This endpoint requires an **organization key** (created under Settings → Organization keys) rather than an agent token.

**`POST /api/v1/inboxes`**

Requires: organization key (`$AGENT_LOADOUT_KEY`)

```bash title="Create an agent + inbox" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/inboxes \
  -H "Authorization: Bearer $AGENT_LOADOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"support","display_name":"Support","metadata":{"tenant":"acme"}}'
```

### Request parameters

<ParamField body="username" type="string" required>
  Local part of the new agent's email address (before the `@`). Must be unique within your organization's sending domain.
</ParamField>

<ParamField body="display_name" type="string">
  Human-readable name for the agent and its inbox, shown in the dashboard and email headers.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs stored on the agent record. Useful for tenant IDs, environment tags, or external references.
</ParamField>

<Note>
  After creating an agent you can issue its token via `POST /api/v1/agents/:id/tokens` — pass `capabilities` to scope it to the exact permissions the agent needs.
</Note>

***

## Get mailbox counts

Returns per-folder message counts and the number of unread conversations for the specified inbox. Use this to drive badges or polling decisions without fetching full thread lists.

**`GET /api/v1/inboxes/:id/counts`**

Requires: `email:read`

```bash title="Get mailbox counts" theme={null}
curl -s https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/counts \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

***

## Add a sender rule

Sender rules run before any classifier. An `allow` rule ensures mail from a trusted address or domain reaches the inbox; a `block` rule sends it straight to Quarantine for a team member to review. You can also list and remove rules — see [Sender Rules](/api-reference/email/messages#sender-rules).

**`POST /api/v1/inboxes/:id/sender-rules`**

Requires: `email:send`

```bash title="Block a domain" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/sender-rules \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"block","pattern":"@spam.example"}'
```

### Request parameters

<ParamField body="kind" type="&#x22;allow&#x22; | &#x22;block&#x22;" required>
  Whether this rule permits (`allow`) or quarantines (`block`) matching mail before the classifier runs.
</ParamField>

<ParamField body="pattern" type="string" required>
  A full email address (`user@example.com`) or a domain prefix (`@example.com`) to match against the sender's `From` header.
</ParamField>

<Tip>
  Prefix a pattern with `@` to match every sender at that domain — for example `@newsletter.example` catches all bulk mail from that domain without listing each address.
</Tip>