Skip to content
Extrovert Extrovert Docs

Update an inbox in a project

PATCH
/v1/projects/{project_id}/inboxes/{inbox_id}

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
project_id
required
string
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

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 (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
project_id

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

string

Responses

Section titled “ Responses ”

200

Section titled “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
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

Section titled “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

Section titled “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

404

Section titled “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