Suppressions

Herald keeps a list of addresses each project no longer mails, and checks it on every send. A suppressed recipient is recorded as suppressed and never sent to; the rest of the email goes as normal.

How addresses get there

Reason	Added when	Stops
`hard_bounce`	The recipient’s server says the address doesn’t exist	Every email
`complaint`	The recipient reports your email as spam	Every email
`unsubscribe`	The recipient unsubscribes from a Proclamation	Proclamations
`manual`	You add it	What you choose
`erased`	You erase a contact at their request	Every email, for good

Each project’s list is its own, and live and test are kept apart. Herald also keeps a short platform-wide list (spam traps, and people who asked Herald itself), which every project’s sends are checked against too; a send it stops is suppressed with "list": "platform" in the event.

Read it

TypeScript

const { data } = await herald.suppressions.list({ reason: 'complaint' })
for (const s of data.data) console.log(s.email, s.reason, s.created_at)
// more: pass data.next as `after`

const { error } = await herald.suppressions.get('ada@example.com')
// error.name === 'not_found': Herald will mail them

An erased person shows no address: only a keyed hash of it is left, so they’re never mailed again by mistake.

Add an address

TypeScript

await herald.suppressions.add({ email: 'ada@example.com' }) // every email
await herald.suppressions.add({ email: 'grace@example.com', scope: 'marketing' }) // Proclamations only

Any key that can send can add one: stopping mail is always safe.

Take one off

TypeScript

await herald.suppressions.remove('ada@example.com')

Only a full-access key can, and only for addresses you added and hard bounces (a mailbox that works again). A complaint, an unsubscribe or an erasure was the person’s choice, so it stays: the answer is suppression_kept (409). Only they can change it, by subscribing again from your preference centre.