Explainer

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

A glossy white push button on a dark dotted board with a glowing candlestick chart

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-Unsubscribe with your URL and List-Unsubscribe-Post with the fixed value List-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.

  1. 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.

  2. 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.

  3. 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.

  4. Click it and watch your platform

    The address should show as unsubscribed within minutes. Two days is the requirement.

  5. 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.

Free estimate

See what this costs your list

Pick your list size. We will show you the math, then send you a one-page cleanup plan for your platform.

Your estimatePick a list size and platform to see the numbers.
—addresses likely dead this year
—paid per year to store them
—contacts that can still be reached

No spam, no list rental. One email with your plan, then nothing unless you ask.

FAQ

Questions about one-click unsubscribe (rfc 8058)

What is one-click unsubscribe?

A method defined in RFC 8058 that lets a mail client unsubscribe a reader with a single click, using two message headers: List-Unsubscribe, which names an HTTPS URL, and List-Unsubscribe-Post, which tells the client it may complete the request with a POST and no further confirmation. Gmail and Yahoo show the resulting link beside the sender name and require the headers on bulk marketing mail.

Is one-click unsubscribe required?

Yes for bulk senders. Since February 2024, Google and Yahoo require RFC 8058 headers on marketing and promotional mail from senders of roughly 5,000 or more messages a day, with requests honored within two days. Microsoft requires a working unsubscribe for Outlook.com and recommends the headers. Transactional mail such as receipts is exempt. Smaller senders are not required to add them, but every major platform does anyway.

How do I add List-Unsubscribe headers in Mailchimp, Klaviyo, or HubSpot?

You usually do not need to. Campaign mail from the major platforms carries both headers automatically, with a per-recipient URL and an endpoint the platform hosts. Confirm it by sending a test to a Gmail address and checking for the unsubscribe link beside the sender name, or by reading the raw headers under "Show original." Developer APIs and self-hosted sending are where you may need to enable or add them yourself.

Why does the unsubscribe link not show in Gmail?

Three common reasons. The headers are missing, which the raw headers will confirm. The message failed DKIM, since Gmail will not offer the link on mail it cannot authenticate. Or Gmail does not yet trust the sending domain enough to show it, which happens with new domains and improves with a few clean campaigns. Check the raw headers first; they settle the first two in a minute.

Does one-click unsubscribe replace the unsubscribe link in the footer?

No. CAN-SPAM still requires a visible unsubscribe mechanism in the message, and Google and Yahoo expect both. The header-based link is an addition that gives the reader an exit before they reach the footer and gives the mail client a way to process it without a web page. Keep the footer link, and make sure it works in one or two steps as well.

Will one-click unsubscribe shrink my list?

Slightly, and only by people who were leaving anyway. The reader who clicks the link at the top of the message would otherwise have pressed the spam button, which counts against your complaint rate while the unsubscribe does not. The list loses a few silent rows your platform was billing for, and your complaint rate stops rising. That is a trade worth making every time.

Clean your list before the next send.

Upload your contacts and every suppression file you have. Download a clean CSV with every column intact. Seven minutes, start to finish.

Envelopes drop into a funnel: good addresses stack up, bad ones are thrown out