Suppression lists
Keep unsubscribed, bounced and opted-out addresses out of bulk mail, and review opt-outs found in replies.
A suppression list holds addresses that bulk mail must skip. Sends and mail merges name a list with listId; how that adds unsubscribe headers and links is in Unsubscribe links.
Lists
- A send naming a list skips every address on that list and on the built-in
globallist. A send naming no list consults neither. - Permanent bounces go on the global list, so one dead address stays off every list.
- The global list cannot be deleted or renamed.
Create a list to give it a name and description. Its id is what sends name as listId and cannot change later.
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 add naming a list that does not exist still works and creates it, named after its id. GET /v1/suppressions returns 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. |
Every source except api emits suppression.created. Adds through the API are recorded in the audit log instead.
Detected opt-outs
Replies and spam reports are detected, not stated, so the optOutHandling setting (PATCH /v1/settings) decides what they do:
| Value | Effect |
|---|---|
review (default) | Replies wait in GET /v1/suppression-reviews with the message they came from and the detection's confidence. A spam report is certain, so it suppresses at once. |
suppress | The address goes on the list at once. |
off | Detected opt-outs are ignored. |
POST /v1/suppression-reviews/{reviewId}/approvesuppresses the address;/dismissdrops the review.- An auto-reply saying the person left the company or changed address always waits for review (source
inactive, global list) under bothreviewandsuppress, since such replies can be wrong or temporary.offignores it. The review lists the addresses the reply names to write to instead.
Unsubscribe links always suppress
The setting covers detected opt-outs only. One-click unsubscribe and the unsubscribe link suppress regardless of it, as RFC 8058 and the Gmail and Yahoo sender rules require.
Delete a list
DELETE /v1/suppressions/{listId}refuses a list that still holds addresses with 409suppression_list_not_empty.- Add
?withEntries=trueto delete its addresses with it. Later sends naming the list reach those addresses again unless the global list holds them. - The list's pending reviews are removed either way.
All routes are in the Suppressions reference.