Pre-check a recipient or list the org's suppression rows

GET

/v1/suppressions

• Production
• Local

With ?recipient= this is the read-only PRE-CHECK: does the CALLER’S OWN ORG suppress this recipient, and which org rows match (returns SuppressionPrecheck). Without ?recipient= it is the paged list of the caller’s own org suppression rows (returns SuppressionPage). Both are strictly scoped to the key’s customer: global/shared_domain/cross-tenant rows are NEVER returned (R4 non-leakage).

Authorizations

• AgentKey
  mailbox:read

Parameters

Query Parameters

recipient

string

Present ⇒ pre-check that address; absent ⇒ list. Canonicalized server-side.

scope

string

Allowed values: org

Optional list filter (only ‘org’ rows are visible here).

include_revoked

boolean

List: include soft-revoked rows (default active-only).

limit

integer

default: 50 >= 1 <= 100

Page size for the cursor-paginated agent surface (default 50; clamped to the 1-100 range).

cursor

string

Opaque list pagination cursor.

Responses

200

A SuppressionPrecheck (when ?recipient= is set) or a SuppressionPage.

One of:

object

The paged list of the caller’s own org suppression rows (newest-first).

object

items

required

Array<object>

One recipient opt-out (suppression) row visible to the caller’s own org. Only org-scope rows are ever returned to the agent/console planes; global and shared_domain rows are operator-only. Rows soft-revoke (revoked_at/by/reason) rather than delete, so opt-out history outlives tenant lifecycle.

object

id

required

Opaque suppression id (sup_…).

string

recipient

required

Canonicalized recipient address (NFC, punycode domain, lower-cased).

string

recipient_raw

The address as originally received.

string

scope

required

Always ‘org’ on these planes (global/shared_domain are operator-only).

string

Allowed values: org

source

required

string

Allowed values: one_click page mailto reply_stop manual complaint escalation

narrow_agent_id

Set on a recipient-chosen ‘just this sender’ narrow row.

string

narrow_mailbox

string

origin_mailbox

The sending mailbox that prompted the opt-out (audit).

string

origin_agent_id

string

origin_message_id

string

reactivation_count

required

Cumulative unsub→revoke→unsub cycles for this row (the §7 abuse input).

integer

created_at

required

string format: date-time

revoked_at

Set when the row was soft-revoked.

string format: date-time

revoked_by

string

revoke_reason

string

revoked

required

boolean

total

required

integer

next_cursor

Opaque cursor for the next page; absent on the last page.

string

object

GET /v1/suppressions?recipient= pre-check result: whether the CALLER’S OWN ORG has an active suppression for the recipient, plus those org rows. Reflects only the caller’s org state; never a global/shared/cross-tenant opt-out (R4 non-leakage).

object

recipient

required

The canonicalized recipient that was checked.

string

suppressed

required

True iff the caller’s org has an active suppression for the recipient.

boolean

rows

required

Array<object>

One recipient opt-out (suppression) row visible to the caller’s own org. Only org-scope rows are ever returned to the agent/console planes; global and shared_domain rows are operator-only. Rows soft-revoke (revoked_at/by/reason) rather than delete, so opt-out history outlives tenant lifecycle.

object

id

required

Opaque suppression id (sup_…).

string

recipient

required

Canonicalized recipient address (NFC, punycode domain, lower-cased).

string

recipient_raw

The address as originally received.

string

scope

required

Always ‘org’ on these planes (global/shared_domain are operator-only).

string

Allowed values: org

source

required

string

Allowed values: one_click page mailto reply_stop manual complaint escalation

narrow_agent_id

Set on a recipient-chosen ‘just this sender’ narrow row.

string

narrow_mailbox

string

origin_mailbox

The sending mailbox that prompted the opt-out (audit).

string

origin_agent_id

string

origin_message_id

string

reactivation_count

required

Cumulative unsub→revoke→unsub cycles for this row (the §7 abuse input).

integer

created_at

required

string format: date-time

revoked_at

Set when the row was soft-revoked.

string format: date-time

revoked_by

string

revoke_reason

string

revoked

required

boolean

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