x402 paid purchase of one or more inboxes
POST /v1/purchase
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
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Base64(JSON) of the signed EIP-3009 payload. PAYMENT-SIGNATURE is also accepted.
Request Body
Section titled “Request Body ”X402 paid-purchase body. The buyer-supplied amount is never trusted; price is server-computed.
object
Number of mailboxes to provision.
Normalized sender name for API mail; up to 60 Unicode characters. No controls, unsupported invisible characters, emoji, address delimiters or deceptive thread markers. Contextually valid Persian and Indic join controls are supported. SMTP preserves its own validated From name. Empty or omitted generates Agent {username}; agent007 becomes Agent 007 and alice_bot becomes Agent alice-bot. If a default cannot be generated safely, it falls back to Agent. Invalid explicit names are rejected.
Responses
Section titled “ Responses ”Settled and provisioned.
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
Opaque inbox id (the path key). Treat as opaque.
Example
pmbx_8f3c2a1bExample
org_1f2eExample
prj_9a8bExample
support@extrovertmail.comExample
agent_3kP9wQExample
Support BotDomain part of the inbox address.
Inbox lifecycle; unknown means readiness evidence is unavailable.
Sender setup evidence. Omitted when unavailable; absence must not be treated as pending or as a send blocker. Review policy is separate.
Mailbox login. Present only on the create response; never persisted in the clear.
Example
587Example
993Inbound webhook registered for this inbox
Effective rolling-24h recipient cap enforced for this inbox.
Whether this inbox is configured for SMTP submission through 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.
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.
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.
Default-off review exceptions for email between inboxes in the sender’s exact project or organization. Every final To, Cc, Bcc and SMTP envelope recipient must resolve to a current inbox inside that scope. Shared domains, aliases, shared administrators and organization hierarchy do not establish membership. Organization enablement covers all current and future projects; project-off does not override it. These settings grant no inbox access. Writing rules, intent, suppression, sending limits and protected onboarding review still apply. Ordinary agents and project managers cannot enable these settings.
object
object
True when the project or organization exception is enabled.
object
Default-off account-wide exception for emails from any account agent to exactly one To recipient: the account human at verified_email, with no Cc or Bcc. Exact address only, not aliases. SMTP envelope must also contain only that recipient. Backend deterministically approves qualifying new submissions as human_recipient_auto; writing rules, intent requirements, suppression and sending limits still apply. Other recipients retain their existing review policy. Protected onboarding practice always requires human review. Only the human or an explicitly authorized account:admin connection can change this setting. Ordinary agents cannot enable it.
object
Invalid request.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Payment required (handshake step 1) or verify/settle failed.
Paid purchase is not enabled.
Per-key rate limit exceeded. Carries a Retry-After header.
The canonical error envelope. error is a stable machine code.
object
Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).
Example
forbiddenHuman-readable detail (never leaks internals).
Example
missing required scopeMachine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.
Consumed plus reserved units.
Requested additional units.
Next UTC usage-period boundary; pending reservations survive this boundary.
Headers
Section titled “Headers ”Seconds until the window resets.