Skip to content
Extrovert Extrovert Docs

List the agent's inboxes

GET
/v1/inboxes

Lists inboxes visible to the key. It never returns passwords or portable credentials.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
limit
integer
default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

page
string

Opaque page token echoed back from a prior next_page. Used by the legacy offset-paginated admin/console list surface; the cursor-paginated agent surface uses Cursor (?cursor) instead.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Ok

object
inboxes
Array<object>

An inbox. id is the canonical opaque inbox id and the path key (/v1/inboxes/{inbox_id}); treat it as an opaque string. address is the within-project email alias. Every redesign resource carries object, org_id, project_id, and timestamps (RFC D9). password is returned only on an explicitly requested, paid create response whose key has mailbox:credentials; list/get responses omit it.

object
object
string
Allowed values: inbox
id

Opaque inbox id (the path key). Treat as opaque.

string
Example
pmbx_8f3c2a1b
org_id
string
Example
org_1f2e
project_id
string
Example
prj_9a8b
address
string
Example
support@extrovertmail.com
agent_id
string
Example
agent_3kP9wQ
display_name
string
Example
Support Bot
password

Mailbox login. Present only on the create response; never persisted in the clear.

string
smtp_host
string
smtp_port
integer
Example
587
imap_host
string
imap_port
integer
Example
993
webhook_url

Inbound webhook registered for this inbox

string
daily_send_limit

Effective rolling-24h recipient cap enforced for this inbox.

integer
>= 1 <= 10000
direct_smtp_enabled

Whether this inbox is configured for direct SMTP submission outside the review pipeline. It is disabled by default, read-only for agents, and can be enabled only by a human administrator for an account with an active paid entitlement. The stored toggle does not grant access after that paid entitlement ends.

boolean
metadata

Arbitrary key-value metadata stored on the inbox (AgentMail parity). Always an object; {} when none is set, never null. Values are string, number, or boolean. Project-scoped: an agent key can only read or mutate metadata for inboxes in its bound project.

object
key
additional properties
One of:
string
effective_review_policy

The RESOLVED review policy for this inbox: the per-inbox override, else the account default, else the require_review floor. Read it once before your first send: under require_review a send/reply/forward WITHOUT an intent is rejected 422 intent_required (nothing sent, nothing queued), and one WITH an intent is queued for a human (202 queued_for_review). Present on the single-inbox GET only; the list response omits it.

string
Allowed values: require_review allow_direct auto_send_graduated
created_at
string format: date-time
next_page
string

401

Section titled “401 ”

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope

403

Section titled “403 ”

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object
error
required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string
Example
forbidden
message

Human-readable detail (never leaks internals).

string
Example
missing required scope