Skip to main content
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
List inboxes

​
Response fields

​
string
Stable inbox identifier (prefix inb_). Pass this to messages, threads, events, and other inbox-scoped endpoints.
​
string
The full email address assigned to this inbox (e.g. support@agents.example.com).
​
string
Human-readable label shown in the dashboard and used as the sender display name.

​
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)
Create an agent + inbox

​
Request parameters

​
string
required
Local part of the new agent’s email address (before the @). Must be unique within your organization’s sending domain.
​
string
Human-readable name for the agent and its inbox, shown in the dashboard and email headers.
​
object
Arbitrary key-value pairs stored on the agent record. Useful for tenant IDs, environment tags, or external references.
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.

​
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
Get mailbox counts

​
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. POST /api/v1/inboxes/:id/sender-rules Requires: email:send
Block a domain

​
Request parameters

​
"allow" | "block"
required
Whether this rule permits (allow) or quarantines (block) matching mail before the classifier runs.
​
string
required
A full email address (user@example.com) or a domain prefix (@example.com) to match against the sender’s From header.
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.