Opt-outs and suppression
Contents
Before a workflow sends anything, PostHog checks two lists: the recipient's opt-out preferences and the project's suppression list. Both live under Workflows in PostHog, and neither is something a workflow can override.
The difference matters. An opt-out is a choice the recipient made – they don't want this kind of message. A suppression is a delivery fact – mail to this address bounced, or you added it by hand, so PostHog stops trying.
Message categories
Opt-outs are organized into message categories, so someone can decline your product newsletter and still get a password reset. Each category has a name, an internal description, a public description shown to recipients on the preferences page, and a type – marketing or transactional.
Create the categories you actually send against, then pick one on each message step in the workflow builder. Recipients who have opted out of that category are skipped.
The opt-out list
The opt-out list shows who has opted out of which category. Recipients land on it in a few ways: a one-click unsubscribe from an email client, the preferences page behind {{unsubscribe_url}} in your email templates, an import from another tool, or you adding them directly.
Every genuine transition from opted-in to opted-out also writes a $workflows_email_unsubscribed event, carrying the category and the source (one_click or preferences_page). See workflow events for the full property list, and note that repeated unsubscribe requests do not emit duplicate events.
Coming from Customer.io? Import your opt-out lists and keep them in sync with a reporting webhook.
The suppression list
The suppression list is address-level and category-independent – a suppressed recipient receives nothing. Each entry records the recipient, how it got there (bounces or manual), the reason or last bounce diagnostic, and when it was suppressed.
PostHog adds addresses automatically when mail to them hard-bounces, which is what protects your sending domain's reputation. You can add an address by hand, and you can remove an entry if you believe the bounce was a one-off – but removing a genuine hard bounce means you'll bounce again.
Related
- Import opt-out lists from Customer.io
- Content library and message templates – adding unsubscribe links to emails
- Workflow events – unsubscribe and bounce events in your project