Revoke (un-suppress) one org-scope suppression row

POST

/v1/suppressions/{id}/revoke

• Production
• Local

Owner-decided revoke (plan §7): an agent may revoke ONLY an org-scope row of its OWN org. The reason is required and audit-logged. A foreign/global/shared id is a 404 (no cross-tenant existence oracle); an empty reason is a 400.

Authorizations

• AgentKey
  mailbox:send

Parameters

Path Parameters

id

required

string

Request Body ^required

Revoke (un-suppress) one org-scope row. The reason is REQUIRED and audit-logged.

object

reason

required

Why the suppression is being revoked (required, audit-logged).

string

Responses

200

The revoked row.

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

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