RFC 8058 Explained: The One-Click Unsubscribe Header Most Senders Still Get Wrong
A visible unsubscribe link in your email footer is not the same as RFC 8058 compliance. Roughly 30% of bulk senders are still non-compliant with the one-click unsubscribe standard that Gmail and Yahoo now enforce, and the most common failure point is the header itself.
This guide explains exactly what RFC 8058 requires, how the one-click unsubscribe mechanism works mechanically, where implementations break, and how to verify your setup before it damages your sender reputation.
What Is RFC 8058?
RFC 8058 is an Internet Engineering Task Force (IETF) standard originally published in 2017. It defines how mailbox providers can offer recipients a true one-click unsubscribe experience directly inside the email client.
The standard went largely unnoticed until February 2024, when Gmail and Yahoo began enforcing it for bulk senders. Full enforcement was live by June 2024. Today, it is a core deliverability requirement for any sender delivering more than 5,000 messages per day to Gmail or Yahoo addresses.
Why the Standard Matters
RFC 8058 exists to solve three specific problems:
- Friction. Recipients who cannot unsubscribe easily are more likely to mark messages as spam. A spam complaint damages sender reputation far more than an unsubscribe.
- Bot-triggered false unsubscribes. Body-link unsubscribes that respond to simple GET requests can be triggered by automated link crawlers, quietly removing engaged subscribers.
- Inconsistent experiences. Without a standard, every sender builds a different unsubscribe flow. Mailbox providers cannot reliably offer a native, consistent opt-out button.
The Two Headers That Make One-Click Unsubscribe Work
RFC 8058 compliance depends on two email headers being present, correctly formatted, and DKIM-signed together:
1. List-Unsubscribe
The List-Unsubscribe header contains the actual unsubscribe mechanism. It must include at least one HTTPS URI that the mailbox provider can send a request to.
You may also include a mailto: URI, but a mailto link alone does not satisfy RFC 8058. A mailto address cannot guarantee an instant, automated, verifiable opt-out action.
Example of a correct header:
List-Unsubscribe: <https://example.com/unsubscribe?id=abc123>, <mailto:unsubscribe@example.com>
2. List-Unsubscribe-Post
The List-Unsubscribe-Post header carries a single fixed value:
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Its only purpose is to tell the mailbox provider that clicking the native unsubscribe button will complete the opt-out immediately, with no further confirmation step.
Both headers must be present together. One without the other does not meet the standard.
How the One-Click Unsubscribe Flow Works
Understanding the mechanical flow matters, because this is where many implementations quietly fail.
| Step |
Action |
Who Performs It |
| 1 |
Recipient opens the email |
Recipient |
| 2 |
Mailbox provider detects valid List-Unsubscribe and List-Unsubscribe-Post headers |
Gmail / Yahoo / Apple Mail |
| 3 |
Native "Unsubscribe" button appears next to the sender name |
Mailbox provider |
| 4 |
Recipient clicks the native button and confirms in a small dialog |
Recipient |
| 5 |
Mailbox provider sends an authenticated HTTP POST request to the HTTPS URI in the List-Unsubscribe header |
Mailbox provider |
| 6 |
Sender server receives the POST and suppresses the address immediately |
Sender |
| 7 |
Address is fully removed from future sends within 48 hours |
Sender |
The critical distinction is step 5. The unsubscribe is not triggered by a person clicking a normal web link. It is triggered by the mailbox provider itself making a structured, authenticated POST request on the recipient's behalf.
That distinction is the source of most compliance failures.
Body-Link Unsubscribe vs. RFC 8058 Header Unsubscribe
Senders often confuse these two mechanisms. They serve different purposes and both are necessary.
| Feature |
Body-Link Unsubscribe |
RFC 8058 Header Unsubscribe |
| Location |
Visible link in email footer |
Hidden email headers |
| Triggered by |
Recipient clicks link |
Mailbox provider sends POST |
| User experience |
Opens browser page |
Single click inside email client |
| Required by |
CAN-SPAM, general best practice |
Gmail, Yahoo bulk sender rules |
| Bot risk |
High if endpoint accepts GET |
None |
| Native button |
No |
Yes |
You need both. The body link covers clients that do not display native unsubscribe buttons. The headers unlock the native button and satisfy provider requirements.
Where Implementations Break: Five Common Mistakes
Mistake 1: Using Only a Body Link
The single most common gap. A visible, clearly labeled unsubscribe link in your footer satisfies CAN-SPAM and general legal requirements. It does not satisfy RFC 8058.
Gmail and Yahoo check specifically for the header structure. A body link that requires the recipient to click through, land on a webpage, and possibly click again does not earn you a native one-click button, no matter how prominent the footer link is.
Mistake 2: The Endpoint Requires a Secondary Action
If your List-Unsubscribe URI leads to a page that asks the recipient to log in, complete a survey, confirm via a second click, or select from a preference center before unsubscribing, you are non-compliant.
RFC 8058 explicitly requires the action to complete with no further steps once the POST request is received.
You can still offer a preference center. Link to it from a confirmation page shown after the unsubscribe succeeds. Do not use it as a mandatory gate.
Mistake 3: Missing or Broken DKIM Coverage
Both headers must be covered by a valid DKIM signature. If your DKIM signing does not extend to these headers, mailbox providers will ignore them, even if the values are perfectly formatted.
This is a quiet failure mode. Everything can look correct in a raw header dump while still failing validation on the receiving end.
If you have recently changed ESPs, rotated signing keys, or modified your DNS records, verify DKIM coverage directly rather than assuming it carried over.
For a broader overview of how email authentication works, see our guide to every email authentication method explained.
Mistake 4: Treating Mailto as Sufficient
Some senders include only a mailto: address in their List-Unsubscribe header, assuming it satisfies the requirement because it is technically valid under the original spec.
It does not meet the one-click bar. There is no way to guarantee the resulting email gets processed automatically and instantly.
Gmail and Yahoo's practical requirement is an HTTPS URI that responds to the POST request directly.
Mistake 5: False Unsubscribes from Bot-Crawled Links
This failure mode confuses teams because it looks like a data problem rather than a header problem.
If your unsubscribe link is a simple clickable URL in the email body that unsubscribes on a plain GET request, automated security scanners, corporate link-safety crawlers, or link-preview bots can trigger an unsubscribe without a human ever clicking.
Recipients get quietly removed from lists they never asked to leave. Nobody notices until list growth numbers look strange.
The RFC 8058 header path avoids this entirely. The action only fires from the mailbox provider's authenticated POST request after a real user clicks the native button. No bot crawling your body copy can trigger it.
Microsoft's Position in 2026
There is conflicting shorthand claiming "Microsoft now requires RFC 8058 too." That is not accurate.
As of 2026, Microsoft does not mandate the RFC 8058 header the way Gmail and Yahoo do. Microsoft's current bulk sender requirement is a functional unsubscribe mechanism, but it stops short of requiring the specific List-Unsubscribe and List-Unsubscribe-Post header pair. Some sources note Microsoft does not currently recognize the List-Unsubscribe-Post header at all, even when present.
That said, Microsoft has signaled that stricter header-based requirements are likely coming. It already applies aggressive authentication and reputation enforcement to consumer Outlook.com and Hotmail domains. For more on how that enforcement shows up, see our breakdown of Microsoft's 2026 Outlook deliverability crackdown.
Practical takeaway: If you are already RFC 8058 compliant for Gmail and Yahoo, you are ahead of wherever Microsoft's rules land next. There is no reason to build a separate, weaker unsubscribe process for Outlook and Hotmail recipients.
Who Needs to Comply
RFC 8058 compliance is not a blanket requirement for every email you send.
Volume threshold: Gmail and Yahoo define bulk senders as those sending 5,000 or more messages per day to their respective domains. Below that volume, you are not formally required to comply, though reputation systems still monitor your sending patterns.
Message type: The requirement applies to marketing and promotional messages only. Transactional emails are explicitly excluded.
| Message Type |
RFC 8058 Required? |
Example |
| Marketing / promotional |
Yes |
Newsletters, sales campaigns, product updates |
| Transactional |
No |
Password resets, order confirmations, shipping notifications |
| Mixed content |
Yes |
Promotional content inside a transactional wrapper |
If you send both types from the same domain, ensure your unsubscribe headers are applied to the marketing stream only. Accidentally including them on transactional sends can cause deliverability issues and confuse recipients.
How to Verify RFC 8058 Compliance
Do not assume your ESP handles this automatically, especially after platform changes, domain changes, or DKIM key rotations.
Step 1: Inspect Your Headers
Send a test marketing email to yourself. View the raw headers and look for:
List-Unsubscribe with at least one HTTPS URIList-Unsubscribe-Post with the exact value List-Unsubscribe=One-Click
Step 2: Confirm DKIM Coverage
Verify that your DKIM signature covers both headers, not just the message body and standard headers. Use a tool or inspect the h= tag in your DKIM-Signature header to confirm List-Unsubscribe and List-Unsubscribe-Post are included.
Step 3: Test the Actual Flow
Trigger the unsubscribe through a supporting client, such as Gmail on the web or Apple Mail. Confirm that no login, survey, or secondary confirmation stands between the click and the completed opt-out.
Step 4: Verify Processing Time
Send a test unsubscribe and confirm the address is fully suppressed from future sends within 48 hours. That is the practical standard Gmail and Yahoo expect.
Step 5: Check for Bot-Triggered False Unsubscribes
If you still maintain a body-link unsubscribe endpoint, ensure it either requires a POST request or includes a confirmation step. Pure GET-based unsubscribe links remain a real source of unintended list churn.
Why Compliance Matters for Deliverability
A sender who makes unsubscribing difficult does not keep more subscribers. They simply convert unsubscribes into spam complaints.
A spam complaint from someone who could not cleanly opt out costs you significantly more sender reputation than a missed open ever will. Mailbox providers weigh complaints heavily in reputation calculations, and a rising complaint rate can trigger bulk folder placement or outright rejection.
If you are troubleshooting deliverability issues, start with compliance fundamentals before testing subject lines or send times. For a full diagnostic, see our guide to why emails go to spam, or run through the ultimate email deliverability checklist.
Related Articles
Related tools: Monitor how unsubscribe patterns affect overall list health with the Email Engagement Score Calculator.
