Create an inbox
POST /v1/inboxes
Create an inbox. Accepts a client-supplied idempotency key (Idempotency-Key header or client_id body field): a retry with the same key returns the existing inbox; the same key with a different body is a 409.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”When the paid-inbox feature flag is on, requests the x402 payment path (HTTP 402).
Header Parameters
Section titled “Header Parameters ”Optional client-supplied key making a CREATE exactly-once. A retry with the same key returns the ORIGINAL response (same status + body) instead of creating a duplicate; the same key with a different request body returns 409. The body field client_id is honored as an alias when this header is absent. The key is scoped per tenant (and per agent on the agent plane), so keys never collide across callers.
Request Body
Section titled “Request Body ”object
Local part. On extrovertmail.com and free.extrovertmail.com it is normalized to lowercase, must contain at least five characters, and must not be postmaster, admin, webadmin, legal, fraudmark, fraudmarc, keith, melissa, richard, sydney, syd, john, or johnny. These restrictions do not apply to customer-owned domains. Omit it for a generated local part.
Must be within the key’s allowed domains. Omit for the account’s plan-appropriate shared domain.
Register an inbound webhook for this inbox.
Optional arbitrary key-value metadata to store on the inbox (AgentMail parity). Values may be string, number, or boolean. Caps: ≤256 keys, ≤256 chars per key, ≤256 chars per string value. Nested objects and arrays are rejected. Echoed back (and replayed on idempotent retries) on the create response.
Optional assertion that must match the key’s bound project; NEVER a selector. A mismatch is 403. The inbox is always created in the key’s stored project.
Optional idempotency key (alias for the Idempotency-Key header). Re-creating with the same key returns the existing inbox rather than a duplicate; the same key with a different body returns 409.
Return the one-time IMAP/SMTP password on a newly created inbox. Requires the mailbox:credentials scope and a paid account. Omit this on ordinary agent/MCP creates.
Responses
Section titled “ Responses ”Created. password is shown once.
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 BotMailbox 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 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.
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.
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 scopeMissing or invalid credential.
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 scopeX402 payment required (feature-flagged).
Authenticated but lacking the required scope, or out of quota.
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 scopeThe supplied idempotency key was already used with a different request body (error = idempotency_conflict).
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 scopePer-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 scopeHeaders
Section titled “Headers ”Seconds until the window resets.