x402 paid purchase of one or more inboxes

POST

/v1/purchase

Production
Local

Performs the x402 handshake: a request with no X-PAYMENT / PAYMENT-SIGNATURE header returns 402 with payment requirements; a signed retry runs verify → settle → provision. Only available when paid inboxes are enabled (otherwise 404).

Authorizations

AgentKey
mailbox:create

Parameters

Header Parameters

X-PAYMENT

string

Base64(JSON) of the signed EIP-3009 payload. PAYMENT-SIGNATURE is also accepted.

Request Body

X402 paid-purchase body. The buyer-supplied amount is never trusted; price is server-computed.

object

quantity

Number of mailboxes to provision.

integer

domain

string

display_name

string

webhook_url

string

Responses

201

Settled and provisioned.

object

payment_id

string

settlement_ref

string

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

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

imap_host

string

imap_port

integer

Example

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

400

Invalid request.

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

402

Payment required (handshake step 1) or verify/settle failed.

404

Paid purchase is not enabled.

429

Per-key rate limit exceeded. Carries a Retry-After header.

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

Headers

Retry-After

integer

Seconds until the window resets.