What this RFC defines
RFC 8058 defines the List-Unsubscribe-Post header, which enables one-click unsubscribe from email newsletters and marketing messages. When a supporting email client shows an Unsubscribe button, clicking it sends an HTTP POST to the URL in this header, rather than opening a browser or sending a reply email.
Where you see it in practice
The Unsubscribe link that appears at the top of Gmail and Apple Mail interfaces for newsletters uses the mechanism defined in RFC 8058. Google and Yahoo made RFC 8058 compliance mandatory for bulk senders (over 5,000 messages per day) starting February 2024. If your List-Unsubscribe-Post header is malformed or the endpoint fails to respond, these mailbox providers can classify your mail as spam.
How it connects to other RFCs
RFC 8058 works alongside RFC 2369 (which defines the older mailto: and http: List-Unsubscribe header). Both headers are typically included together: RFC 2369 for compatibility with older clients, RFC 8058 for one-click POST support in modern clients. The two complement rather than replace each other.
Current status
RFC 8058 is a current standard, published January 2017. It became practically mandatory in February 2024 when Google and Yahoo required one-click unsubscribe for bulk senders. All major ESPs now generate RFC 8058-compliant headers automatically.
One-click unsubscribe
RFC 8058 defined the List-Unsubscribe-Post header in February 2017, extending RFC 2369 with a “one-click” unsubscribe mechanism. The sender includes both List-Unsubscribe: and List-Unsubscribe-Post: List-Unsubscribe=One-Click in the headers. When a mail client wants to unsubscribe on behalf of the user, it sends an HTTP POST to the URL with body “List-Unsubscribe=One-Click”, and the server processes the unsubscribe without further user interaction.
Google and Yahoo enforcement
In February 2024, Google and Yahoo announced that bulk senders (5,000+ messages per day to their respective services) must implement RFC 8058 one-click unsubscribe by June 2024. This drove rapid adoption: most ESPs (Mailchimp, Klaviyo, HubSpot, SendGrid, Mailgun) added RFC 8058 support to their default templates within weeks. Any bulk sender not implementing one-click unsubscribe in 2026 sees measurable deliverability degradation to Gmail and Yahoo Mail recipients.
Implementation requirements
The RFC 8058 endpoint must accept HTTP POST (not just GET), respond within a short timeout (typically 5-10 seconds), and not require authentication beyond what is in the URL. The URL should include a signed or otherwise unguessable token so an attacker cannot mass-unsubscribe legitimate subscribers. The unsubscribe should take effect within 24 hours per Google requirements. Some senders use HTTPS-only endpoints; others require CSRF-token headers, though the RFC only mandates the POST body format.
RFC 8058 (January 2017) defines Signaling One-Click Functionality for List Email Headers: the List-Unsubscribe-Post header that lets mail clients unsubscribe users with a single POST request without additional user interaction. Complements RFC 2369 List-Unsubscribe. Mandatory since February 2024 for bulk senders per Gmail and Yahoo Sender Requirements. Foundation for the toolbar “Unsubscribe” button that works in one tap in Gmail, Yahoo Mail, iCloud, and other modern clients.
RFC 8058 at a glance
| Aspect | Detail |
|---|---|
| Purpose | Enable one-click unsubscribe via HTTP POST without user interaction |
| Header | List-Unsubscribe-Post: List-Unsubscribe=One-Click |
| Companion header | RFC 2369 List-Unsubscribe (must include HTTPS URL) |
| Client action | POST to List-Unsubscribe HTTPS URL with body List-Unsubscribe=One-Click |
| Mandatory since | February 2024 (Gmail and Yahoo bulk sender requirements) |
| Effect time | Within 24 hours per Gmail requirements |
| Published | January 2017 |
One-Click mechanism
Gmail and Yahoo 2024 requirements
| Requirement | Gmail (Feb 2024) | Yahoo (Feb 2024) |
|---|---|---|
| Bulk sender threshold | 5000+ messages per day to Gmail addresses | 5000+ messages per day to Yahoo addresses |
| List-Unsubscribe required | Yes (HTTPS URL) | Yes (HTTPS URL) |
| One-Click required (RFC 8058) | Yes | Yes |
| Effect time | Within 24 hours | Within 24 hours |
| Spam complaint threshold | Under 0.3% (target under 0.1%) | Similar |
| Consequences of non-compliance | Reduced deliverability, spam folder placement, eventual blocking | Similar |
Common One-Click implementation mistakes
?u=12345&t=xyz). The POST body only contains List-Unsubscribe=One-Click as the trigger. Servers that ignore URL parameters cannot identify who to unsubscribe.Related standards and further reading
- RFC 2369 List-* URLs Guide: parent header family
- SPF Record Guide: bulk requirement component
- DKIM Record Guide: bulk requirement component
- DMARC Record Guide: bulk requirement component
Frequently asked questions
Do I need RFC 8058 one-click for my newsletter?
Yes if you send 5000+ messages per day to Gmail or Yahoo addresses (per their February 2024 requirements). Below that threshold, RFC 8058 remains recommended but not strictly required. Any modern bulk sender should implement it: reduces spam complaints (users unsubscribe instead of marking spam), improves deliverability signals, and is user-friendly.
What is the difference between RFC 2369 List-Unsubscribe and RFC 8058 List-Unsubscribe-Post?
List-Unsubscribe (RFC 2369) provides URLs for the client to open on user click; user takes action (fills form, sends email). List-Unsubscribe-Post (RFC 8058) is a signal telling the client “you may POST to the HTTPS URL directly without user interaction.” Both are needed for the toolbar one-click button in Gmail/Yahoo. Emit both on every bulk message.
How do I secure the one-click endpoint against abuse?
Signed tokens in URL parameters. Include a token (t=abcxyz) that encodes the user ID and a signature; verify on POST that the token matches the claimed user ID. This prevents attackers from unsubscribing arbitrary users by guessing IDs. Additional defenses: rate limiting per source IP, HTTPS-only enforcement, refusing overly frequent unsubscribes for the same address. CSRF tokens are not strictly required per RFC 8058 (mail clients not browsers make the POST) but do not hurt.
What happens if the POST fails?
The client typically shows an error to the user, and the unsubscribe does not take effect. Mail clients should retry appropriately or fall back to the mailto: URL. Server-side: log the failure for investigation; monitor unsubscribe failure rates and address any recurring issues promptly (server errors, misconfigured endpoints impact deliverability).
How quickly must the unsubscribe take effect?
Within 24 hours per Gmail bulk sender requirements. This means the next sending job after the unsubscribe request must honor it. Weekly batch processing is too slow. Modern architecture: queue unsubscribes for processing every few minutes or in real-time; verify on each send that the recipient is still opted in. Slow processing has direct deliverability impact.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
