Update an inbox (rename the sender identity / metadata in place)

PATCH

/v1/inboxes/{inbox_id}

• Production
• Local

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

• AgentKey
  mailbox:create mailbox:read
• AgentKey
  mailbox:quota mailbox:read

Parameters

Path Parameters

inbox_id

required

string

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

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 (display name falls back to the local part at the mail layers).

object

display_name

Sender display / “From” name. Propagated to the inbox and the authenticated sender.

string

webhook_url

Replace the inbox’s inbound webhook target (empty string clears it).

string

daily_send_limit

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.

integer

>= 1 <= 10000

metadata

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.

object

key

additional properties

One of:

string

string

number

number

boolean

boolean

null

null

project_id

Optional assertion that must match the key’s bound project; NEVER a selector. A mismatch is 403.

string

Responses

200

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

object

string

Allowed values: inbox

id

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

587

imap_host

string

imap_port

integer

Example

993

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

string

number

number

boolean

boolean

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

401

Missing or invalid credential.

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

403

Authenticated but lacking the required scope, or out of quota.

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

404

Resource not found.

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