One-Click Unsubscribe (RFC 8058): What It Is and How to Turn It On

There is an unsubscribe link at the top of some messages in Gmail, next to the sender's name, and not at the top of others. The difference is two lines in the message headers that the reader never sees. Senders who have them give anyone who wants out a clean, one-click exit. Senders who do not get the spam button instead.
Since February 2024, Gmail and Yahoo have required those headers on bulk marketing mail. This guide explains what they are, line by line, who must include them, how the major platforms handle them (mostly for you), how to confirm yours are working with a single test message, and why a list that is easy to leave ends up healthier than one that is not.
Key takeaways
- One-click unsubscribe is two headers from RFC 8058:
List-Unsubscribewith your URL andList-Unsubscribe-Postwith the fixed valueList-Unsubscribe=One-Click. - Gmail and Yahoo require them on bulk marketing mail and require the request to be honored within two days.
- Nearly every major email platform adds them automatically. Confirm by sending a test to a Gmail address and looking for the link beside the sender name.
- The headers lower your complaint rate, not your list size. Keep the unsubscribes out of every future import so they never have to leave twice.
What one-click unsubscribe is
Marketing email has carried an unsubscribe link in the footer for 20 years, because CAN-SPAM requires one. One-click unsubscribe is different. It lives in the message headers, where the mail client reads it, and it lets Gmail, Yahoo, and other clients offer the reader a way out that does not involve scrolling to the footer, loading a web page, or confirming anything. The reader clicks once, the client sends a request to your server, and the subscription ends.
The standard is RFC 8058, published in 2017. It builds on an older header, List-Unsubscribe, which let clients offer a link or a mailto address, and adds a second header that tells the client it may complete the request with an HTTP POST and no human interaction. That second header is what makes it one click. Without it, the client either shows nothing or opens your unsubscribe page in a browser, which is better than nothing and short of the standard.
From the reader's side, the whole thing is a small link labeled "Unsubscribe" beside the sender name. From yours, it is two lines your platform almost certainly already writes.
The two headers, line by line
A compliant message carries both of these:
List-Unsubscribe: <https://yourdomain.com/unsubscribe?id=abc123>List-Unsubscribe-Post: List-Unsubscribe=One-Click
The first names the URL the client should call, in angle brackets, over HTTPS. The identifier in the URL is how your system knows who is leaving. It is per recipient, which is why the header is generated at send time rather than written once. An older mailto form is also allowed in the same header, separated by a comma, and some platforms include both.
The second is a fixed string. It never changes, and its presence is the signal that your server will accept a POST request to the URL above and treat it as a completed unsubscribe. The client sends that POST with the body List-Unsubscribe=One-Click and expects a success response. No redirect to a page, no "are you sure," no login.
The standard also requires the message to carry a valid DKIM signature covering these headers, so that nobody can forge an unsubscribe request in your name. That ties this rule to the authentication rules in SPF, DKIM, and DMARC for email marketers, and it is why a missing link is sometimes an authentication problem in disguise.
The link beside the sender name is Gmail's, not yours. You do not design it, place it, or style it. You supply two headers and a server that accepts a POST. Gmail decides where and whether it shows, which is why the only reliable check is sending a test and looking.
Who requires it and on which mail
Google requires the headers on marketing and promotional messages from bulk senders, meaning around 5,000 messages a day to Gmail, and requires the request to be processed within two days. Yahoo requires the same for bulk marketing mail. Microsoft requires a working unsubscribe for Outlook.com and recommends the one-click headers; check its current guidelines for whether that has hardened. The full comparison is in bulk sender requirements.
Transactional mail is exempt: receipts, password resets, shipping notices, account alerts. The test is whether the reader could reasonably want to stop receiving it without closing their account. A weekly digest is marketing. An invoice is not. A receipt with a promotion attached is safest treated as marketing.
Senders under the bulk threshold are not required to add the headers, but there is no reason to leave them off. Platforms add them regardless of volume, and Gmail shows the link for small senders too. Two days is the deadline for honoring the request. Most platforms process it in seconds.
Send a test to a Gmail address
Use a real campaign or a test of one, from the same sending domain and pipeline as your live mail.
Look beside the sender name
Open the message in Gmail on the web. With the headers present and the mail authenticated, an "Unsubscribe" link appears next to the sender at the top.
Read the raw headers if the link is missing
Choose "Show original" and search for List-Unsubscribe and List-Unsubscribe-Post. Confirm dkim=pass appears in the same view.
Click it and watch your platform
The address should show as unsubscribed within minutes. Two days is the requirement.
Repeat after any change
Run the same test whenever you switch platforms, sending domains, or the pipeline that sends your automations.
How the major platforms handle it
If you send campaigns through Mailchimp, Klaviyo, HubSpot, ActiveCampaign, Constant Contact, MailerLite, Kit, Brevo, or any of their peers, the headers are added to campaign mail without a setting to find. The platform generates the per-recipient URL, hosts the endpoint that receives the POST, and updates the contact's status when it arrives. For most of them this was true before the 2024 deadline.
Where it can go wrong is at the edges. Automated sends sometimes travel through a separate pipeline from campaigns, which is fine for a receipt and not fine for a drip sequence. Mail sent through a developer API, such as SendGrid's, often requires you to enable a subscription-tracking or list-management feature, or to add the headers yourself. Self-hosted senders add everything by hand, plus the endpoint that receives the request.
If you are unsure which category you fall into, do not hunt for the setting. Send the test described below and read the headers. They are present or they are not, and the message will tell you in under a minute.
How to confirm it is on
The check takes one test message and a Gmail account you control. Send a real campaign, or a test of one, from the same sending domain and pipeline as your live mail; a test from a different pipeline proves nothing. Open it in Gmail on the web and look beside the sender name at the top. If the headers are present and the message is authenticated, a link labeled "Unsubscribe" appears there.
If it does not, open the message menu and choose "Show original." Search the raw headers for List-Unsubscribe and List-Unsubscribe-Post. If both are present but the link is missing, check that dkim=pass appears in the same view, since Gmail will not offer the link on mail it cannot authenticate. Gmail may also withhold the link from a sending domain it does not yet trust, so a new domain with correct headers may need a few campaigns before it shows. The raw headers are the ground truth.
Then click it. Within a few minutes the address should show as unsubscribed in your platform; within two days is the requirement. Repeat the check whenever you change platforms, sending domains, or the pipeline that sends your automations.
Why it lowers your complaint rate, not your list size
The fear is that an easy exit empties the list. The arithmetic says otherwise. The reader who clicks unsubscribe at the top of the message was going to leave one way or another. The only question was which button. The spam button counts against your Postmaster Tools rate, where Google wants under 0.1% and penalizes 0.3%. The unsubscribe link counts for nothing. One-click moves the same departure from the column that damages you to the column that does not.
The list does get smaller, by exactly the people who were not reading it. On a 25,000-address list, a few hundred unsubscribes after turning on one-click means a few hundred fewer contacts your platform bills you for at roughly $0.01 to $0.03 a month each, a few hundred fewer silent rows dragging down placement, and a complaint rate that stops creeping toward the line. Spam complaint rate explained has the numbers, and the unsubscribe is not your enemy makes the longer case.
Keep the unsubscribes out for good
An unsubscribe honored once is not honored forever if the address comes back. The usual route is an import: a CRM export, a spreadsheet from a trade show, a list migrated to a new platform. The suppression flag stays behind, the address returns as a fresh contact, and a person who left by the clean exit now has a reason to use the other one.
Treat your unsubscribe export as a permanent suppression list, the idea explained in what is an email suppression list. Before any file enters any platform, upload it to Email List Refresh with that export, plus your bounces and complaints, as suppression files, and download the original CSV with every column intact and every suppressed address gone. It takes about seven minutes. The person who left stays gone, and the complaint they would have filed on their second unwanted message never happens.