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.
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.
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 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.
Missing 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 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.
X402 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 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.
The 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 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.
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.