List / search the org's suppression rows

GET

/v1/admin/orgs/{org_id}/suppressions

• Production
• Local

The org’s recipient opt-out (suppression) rows, newest-first. Only org-scope rows are visible; global/shared-domain rows are operator-only. Supports ?recipient=, ?scope=, ?include_revoked=true, and limit/cursor paging.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

Query Parameters

recipient

string

Filter by (canonicalized) recipient.

scope

string

Allowed values: org

include_revoked

boolean

limit

integer

default: 50 >= 1 <= 100

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

cursor

string

Responses

200

Ok

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

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