Handling email opt-outs correctly means more than adding an unsubscribe link. It requires a suppression system that is actually enforced at send time, per-category preferences that let recipients stay subscribed to the messages they value, and automatic suppression of addresses that bounce or generate complaints. When those three pieces work together, you stay compliant, your sender reputation stays intact, and recipients trust that their preferences are actually respected.
Why Suppression Is a First-Class Concern
Email deliverability depends heavily on recipient signals. An address that bounces permanently is no longer reachable. An address that hits the spam button tells mailbox providers that your sending domain is a problem. Continuing to send to either category drives up complaint rates, which cascades into reduced inbox placement for every message you send — including the transactional ones that matter most.
This is why suppression cannot be an afterthought layered onto a general notification system. The suppression list needs to be a single authoritative source of truth that every outbound send path consults before dispatching. If two separate systems each track preferences, at least one of them will eventually get out of sync with the other, and the wrong one will win at send time.
Beyond deliverability, recipients have legal rights. The CAN-SPAM Act, CASL, and GDPR all require honoring unsubscribe requests promptly. One-click unsubscribe, standardized in RFC 8058, is increasingly required by major mailbox providers for bulk senders. Building to that standard protects both compliance posture and sender reputation. For a broader look at how GDPR erasure rights apply to AI platforms, see GDPR for AI systems: data subject rights and erasure.
The Suppression Table as the Single Source of Truth
A robust suppression architecture centers on a single authoritative store of suppressed addresses, each record keyed by address and category scope. The scope dimension is what allows per-category preferences without requiring a separate opt-out system for each category. A broad scope suppresses the address from every non-transactional send. A narrower scope — a specific category like a digest or report type, for example — suppresses only that category while allowing other sends through.
A key invariant: suppression at a broad scope must imply suppression at every narrower scope. If someone opts out of all email, checking only for a narrow category suppression and finding none should not let a send through. The check must walk the scope hierarchy.
Every record should carry a source field indicating how the suppression was created: from a one-click unsubscribe link, a user preference toggle, a mailbox provider bounce, or a spam complaint. That audit trail helps when a recipient contacts support saying they are still receiving email — you can look up exactly what happened and when.
One-Click Unsubscribe
RFC 8058 one-click unsubscribe works by embedding a List-Unsubscribe header in every bulk message. The header contains a URL that a mail client can POST to directly, suppressing the address without requiring the recipient to visit a web page or log in. This is the flow that Gmail and Yahoo now require for senders above certain volume thresholds.
The URL must be stateless and tamper-resistant without requiring a session. A common pattern is a short-lived HMAC-signed token that encodes the recipient address and scope. When the POST arrives, the server verifies the signature, checks that the token has not expired, and records the suppression. No authentication is required from the recipient — the token itself is the credential.
The same token works for a browser-visible unsubscribe page. A recipient who clicks the link in an email client sees a simple confirmation rather than a login prompt. This matters for accessibility: forcing login at the unsubscribe step frustrates recipients and, in some jurisdictions, is treated as an illegal barrier to opting out.
Because these endpoints are public-facing, replay protection matters. A token that has already been used to suppress an address should not be re-usable in a different context, and a token presented with a timestamp far in the past should be rejected. The suppression operation itself is idempotent — suppressing an already-suppressed address is harmless — but the token validation layer should not be.
Automatic Suppression from Mailbox Provider Feedback
Mailbox providers send bounce and complaint notifications back to senders via webhooks. A permanent bounce means the address does not exist or cannot receive mail. A complaint means the recipient marked your message as spam. Both events should trigger automatic suppression.
The webhook endpoint is public-facing by design — it must accept unauthenticated POSTs from the provider's infrastructure. This means the only trust signal is a cryptographic signature included in the request. Verifying that signature before processing any event is non-negotiable; an unsigned or unverifiable event should be rejected entirely, not processed with reduced trust.
Freshness checking matters too. A webhook body delivered hours or days late should be treated with suspicion. A five-minute window on the event timestamp, combined with a replay cache for recently seen event identifiers, covers the most common attack vectors against webhook endpoints.
A sound implementation handles provider bounce and complaint events through a signature-verified webhook path that automatically records suppression at the broadest scope when a permanent failure or complaint is received. This ensures suppression fires regardless of which specific email category triggered the event. For how webhook signature verification applies across the platform more broadly, see webhook security: signing and verifying events.
Per-Category Preference Centers
A preference center gives recipients finer control than a binary opt-in or opt-out. Instead of choosing between receiving everything and receiving nothing, a recipient can disable weekly digests while keeping security alerts, or opt out of marketing reports while staying subscribed to billing notifications.
From an implementation standpoint, a preference center is a thin layer over the suppression store. Each toggle maps to a specific scope. Enabling a category removes the suppression for that scope; disabling it records one. The send-time check is unchanged — it still consults the suppression store.
The important design constraint is that the preference center must only expose non-transactional categories. Transactional email — password resets, payment receipts, security alerts triggered by account activity — should not be suppressible through a preference center. Those messages exist to protect the recipient, not to market to them. Making them opt-out creates both a legal and a safety risk.
The scope design should map cleanly to the categories exposed in the UI. If a recipient disables a category in the preference center, the send path for that category must check for its suppression. If the scope names used in the suppression store do not match the categories the UI presents, mismatches will silently let suppressed sends through.
Handling Re-subscription
Recipients change their minds. An unsubscribe mechanism that has no re-subscribe path leaves them stranded. The preference center is the natural home for re-subscription: a recipient who opted out can log in, navigate to preferences, and re-enable specific categories.
For one-click unsubscribes, the re-subscribe path typically requires authentication, since the stateless token model is not appropriate for authorizing changes that increase the volume of email sent. This is acceptable — the asymmetry reflects the asymmetry of risk. Opting out is low-risk and should be frictionless. Opting back in warrants a small amount of friction to confirm intent.
It is also worth designing a suppression override for transactional sends. If an address is globally suppressed but the event is a security alert or account warning, the platform may need to deliver that message regardless. The scope hierarchy handles this cleanly: transactional sends simply bypass the suppression check, or check against a transactional scope that preferences cannot set.
What Gets Logged
Every suppression event should be logged with enough detail to reconstruct the history: the address, the scope, the source, and the timestamp. When a recipient contacts support claiming they never unsubscribed, or when a compliance audit asks for proof that opt-outs were honored within a defined timeframe, that log is what you produce.
Storing suppression source alongside every entry — whether it originated from a one-click unsubscribe, a preference center toggle, a bounce, or a spam complaint — makes the suppression history legible to support staff and auditable for compliance purposes. For related coverage of how transactional emails and notification templates are structured, see transactional email and templates.
Common questions
If a user unsubscribes via the one-click link, can they still receive transactional email like password resets?
Yes. One-click unsubscribe suppresses a scope — typically a specific category or all non-transactional email. Transactional sends like password resets and security alerts operate outside that scope and are not affected by the suppression. The distinction between transactional and non-transactional must be enforced at the point of dispatch, not left to the suppression check alone.
How should bounces from a shared address (like a team inbox) be handled?
Permanent bounces should suppress the specific address that bounced, not the domain or any other address. If a team inbox bounces because it is over quota, that is a temporary condition — most providers classify it as a soft bounce and will not fire a permanent failure event. Hard bounces indicating an invalid address should suppress only that exact address. Avoid domain-level suppression unless you have a specific compliance reason; it is too blunt and will suppress valid recipients.
What is the right retention period for suppression records?
Suppression records should be kept indefinitely, or at minimum for the period required by the email regulations applicable to your recipients. Deleting a suppression record is equivalent to re-subscribing someone without their consent — if a recipient opted out and the record is purged, future sends will reach them again. Most compliance frameworks require that you be able to demonstrate you honored an opt-out request; keeping the record is how you do that.
How does suppression interact with GDPR erasure requests?
This is a tension worth designing for explicitly. When a user exercises a GDPR right-to-erasure request, the goal is to remove personal data — but the suppression record itself contains an email address and serves a compliance purpose (proving the opt-out was honored). A common approach is to retain the suppression record in hashed or pseudonymized form after erasure, preserving the opt-out proof without keeping the raw address. Check with your legal team on the right balance for your jurisdiction. See GDPR for AI systems: data subject rights and erasure for broader context.
For a full picture of how platform notifications work alongside agent alerts and operational events, see in-app notifications that cut through and slack and multi-channel alerting.