Suppression lists

Named lists, unsubscribes and bounces, and reviewing opt-outs found in replies.

Lists

A send that names a list with listId gets one-click unsubscribe headers and skips every address on that list and on the built-in global list. A send naming no list consults neither. Permanent bounces go on the global list, so one dead address stays off every list.

Create a list to give it a name and description. Its id is what sends name as listId; it cannot change later.

curl

SDK

curl -X POST "https://api.workwae.com/v1/suppressions" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "id": "weekly-news",
  "name": "Weekly news",
  "description": "The Friday newsletter"
}'

A send or an add naming a list that does not exist still works and creates it, named after its id, so callers that never created their lists keep working. GET /v1/suppressions answers every list, global first, with its count of addresses by source.

How addresses get on a list

Source	Meaning
`unsubscribe`	The recipient used the one-click header or the unsubscribe link.
`bounce`	A permanent bounce said the address is gone. Always the global list.
`api`	You added it with `POST /v1/suppressions/{listId}/entries`.
`reply`	A reply asked to stop receiving the mail, as detected by workwae.
`complaint`	The recipient's provider forwarded a spam report (ARF).
`inactive`	An auto-reply said the person left or moved to another address, as detected by workwae, and you approved its review. Always the global list.

Only unsubscribe, bounce, reply, complaint and inactive suppressions emit suppression.created. Adds through the API are recorded in the audit log instead.

Detected opt-outs

Replies and spam reports are detected rather than stated, so the optOutHandling setting (PATCH /v1/settings) decides what they do:

review (the default): replies wait in GET /v1/suppression-reviews with the message they came from and how sure the detection was. POST /v1/suppression-reviews/{reviewId}/approve suppresses the address; /dismiss drops the review. A spam report is certain, so it suppresses at once.
suppress: the address goes on the list at once.
off: they are ignored.

An auto-reply saying the person left the company or changed address waits for review (source inactive, on the global list) under both review and suppress, since such replies can be wrong or temporary; off ignores it. The review lists the addresses the reply names to write to instead.

Deleting a list

DELETE /v1/suppressions/{listId} refuses a list that still holds addresses with 409 and reason suppression_list_not_empty. Add ?withEntries=true to delete its addresses with it: later sends naming the list reach those addresses again unless the global list holds them. Its pending reviews go either way. The global list cannot be deleted or renamed.

Every route is in the Suppressions reference.