Automated security tools can open links in incoming email. A link visit alone is therefore insufficient evidence that a recipient wants to unsubscribe.
How does one-click distinguish an unsubscribe request from a link visit?
One-click uses an HTTP POST request after recipient consent, rather than treating a fetched link as an opt-out.
RFC 8058 requires the receiving system to obtain user consent before making that request.
The sender can then process the opt-out without a login or confirmation page. An easy unsubscribe also gives recipients an alternative to reporting unwanted messages as spam.
Which headers must the message contain?
The message needs one List-Unsubscribe header and one List-Unsubscribe-Post header.
The first supplies the unsubscribe destination. The second contains the exact value List-Unsubscribe=One-Click. Google's sender guidelines show this pair:
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://solarmora.com/unsubscribe/example>Use an HTTPS URL for the destination to protect unsubscribe requests from interception. Additional non-HTTP destinations, such as a mailto address, are permitted.
Sign both headers with DKIM. Include them in the signature's h= list of covered headers. Without the required valid signature, RFC 8058 advises receivers not to offer the one-click control. Supplying the headers alone therefore does not guarantee a button.
What must the unsubscribe endpoint accept?
The endpoint must accept the one-click POST without requiring a login, cookies or HTTP authorization. The receiving mail system makes the request without the recipient's website session.
Its URL must identify the recipient and the list to remove them from, because no session supplies that context. The POST body carries the fixed pair List-Unsubscribe=One-Click.
Use a hard-to-forge identifier in the URL, because a predictable address could let someone unsubscribe another recipient. Validate that identifier before applying the request.
The sender must not return an HTTPS redirect. A redirect can change how a POST is handled, so the published endpoint must process the request directly. A 3xx redirect response therefore fails this requirement.
What if a firewall blocks the request?
A blocked request can still leave the sender responsible for an unprocessed unsubscribe.
Google's Compliance status dashboard counts successful unsubscribe requests even when an intermediary prevents them from reaching your servers.
A bot challenge requiring a browser session conflicts with an anonymous one-click POST. Configure the endpoint's access rules so legitimate requests can reach it. An empty application log does not prove that no recipient tried to unsubscribe.
Does one-click replace the link inside the message?
No, Google and Yahoo also require a visible unsubscribe link in the body of marketing and subscribed messages.
Google requires the RFC 8058 method for the header-based control. Yahoo's guidance recommends that method and also accepts mailto in its list-unsubscribe header.
The body link gives recipients another way to request removal. It remains necessary even when a mail client displays its own control.
How quickly must you process the request?
Google and Yahoo require honoring unsubscribe requests within two days.
Google expresses the deadline as 48 hours in its compliance dashboard. A request made Monday at noon must therefore be processed by Wednesday at noon.
The deadline concerns removing the recipient from the list. A working endpoint that leaves the recipient subscribed beyond that point fails the processing requirement.
How do you use Bird's unsubscribe handling?
You classify a send as marketing so Bird supplies its managed unsubscribe handling.
The API's category field accepts marketing for promotional mail or transactional for operational messages. Without an explicit category, a send using a reusable template inherits its classification. Other sends default to marketing.
Bird adds the unsubscribe header pair to marketing messages and includes it in the signed content. Its hosted endpoint records the opt-out. Future marketing sends respect that suppression, the record that prevents delivery to an opted-out address.
For individual HTTP API sends, leave both marketing unsubscribe headers to Bird. Supplying either managed header returns 422. When you send to an audience with Bird's broadcasts, Bird discards any marketing unsubscribe headers you supply. SMTP submissions also discard those headers.
Bird does not automatically add the managed pair to transactional messages. Individual HTTP API sends can pass through custom unsubscribe headers on that category.
The unsubscribe-links guide explains the visible body link and default footer. Categories explains how classification affects delivery to opted-out recipients.
In short
RFC 8058 uses a pair of headers.
List-Unsubscribe provides the HTTPS destination, and List-Unsubscribe-Post identifies the one-click request.
The signature must cover both headers.
A valid DKIM signature must include both unsubscribe headers in its signed list.
The endpoint needs no login or redirect.
The request carries its identifying information in the URL and must work without cookies or authorization.
Visible links and timely processing still matter.
Provider requirements include an in-body unsubscribe link and processing within two days.