Update an inbox (rename the sender identity / metadata in place)
PATCH /v1/inboxes/{inbox_id}
Update cheap inbox metadata (e.g. the sender display name) without delete+recreate. Owner-scoped: a cross-tenant or cross-agent target is a 404. Returns the updated inbox.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Opaque inbox id (the canonical path key). The inbox’s email address is also accepted here as a within-project alias. Treat the id as opaque.
Request Body required
Section titled “Request Body required ”Cheap, in-place inbox settings an owning agent may change without delete+recreate. Every field is optional; an omitted field leaves the stored value untouched (PATCH semantics). Sending an empty string clears a display/webhook field (cleared names emit a bare address in API mail).
object
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 string clears; omitted or null leaves unchanged.
Replace the inbox’s inbound webhook target (empty string clears it).
Replace the inbox’s rolling-24h recipient cap. Requires mailbox:quota in addition to mailbox:read; ordinary create/send keys cannot raise their own safety throttle.
Patch the inbox’s arbitrary metadata (AgentMail parity). Shallow merge: an omitted metadata leaves it unchanged; an object merges into the existing metadata; a key whose value is null deletes that key; a top-level metadata: null clears ALL metadata (the response then carries {}). Values may be string, number, or boolean; a per-key null value DELETES that key (the documented delete mechanism); nested objects/arrays are rejected; the same ≤256 key/length caps as create apply.
Optional assertion that must match the key’s bound project; NEVER a selector. A mismatch is 403.
Responses
Section titled “ Responses ”Ok
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.
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.
Resource not found.
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.