Add an allow/block entry to an inbox's contact lists

POST

/v1/inboxes/{inbox_id}/lists

• Production
• Local

Add one allow/block entry (address or domain) to this inbox’s contact lists. A block entry rejects a matching recipient on send; when any allow entry exists, sends from this inbox are restricted to recipients that match one of them (allowlist mode). Account-wide entries (registered on any inbox the agent owns) also apply.

Authorizations

• AgentKey
  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

Add one allow/block entry to an inbox’s contact lists. pattern is a bare email address (matched in full) or a bare domain (matches any address in that domain). A block entry rejects a matching recipient; when any allow entry exists, sends are restricted to recipients that match one (allowlist mode).

object

kind

required

Whether this entry permits (allow) or rejects (block) a match.

string

Allowed values: allow block

direction

Traffic direction the entry governs. Only send is enforced today (at outbound time); receive is accepted for forward-compatibility.

string

default: send

Allowed values: send receive

pattern

required

A bare email address or a bare domain (e.g. acme.com).

string

Responses

201

Created.

One allow/block contact-list entry. inbox is null when the entry is account-wide (covers every inbox the agent owns).

object

id

string

inbox

string

nullable

kind

string

Allowed values: allow block

direction

string

Allowed values: send receive

pattern

string

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

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

409

Resource conflict (e.g. a duplicate entry).

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