One-Click Unsubscribe (RFC 8058): What Gmail and Yahoo Now Require

What “one-click unsubscribe” means

There are two different unsubscribe paths in a marketing email, and it helps to keep them apart:

1. The link in the email body. The familiar “Unsubscribe” link in the footer. You design it, it opens a page on your side, and it may show a confirmation or a preference page.
2. The unsubscribe option in the mail app. In Gmail, for example, an “Unsubscribe” option can appear at the top of the message next to the sender name. It isn’t part of your email design at all. The mail app builds it from hidden lines at the top of the message, called headers.

One-click unsubscribe is about the second path. When your message carries the right headers, the mail app can unsubscribe the reader for you in the background: the reader confirms in the app, and the app sends a request straight to your unsubscribe address. Nobody has to load a page, log in or confirm anything on your site.

Why do mailbox providers care? Because a reader who can’t find an easy way out often clicks “Report spam” instead. Spam reports count against the sender, and both Gmail and Yahoo publish spam-rate thresholds. Making the exit easy is better for the reader and, in practice, better for your sender reputation.

The two headers, in plain language

One-click unsubscribe uses two email headers. You won’t normally see them, but they look like this inside the raw message:

List-Unsubscribe: <https://your-store.example/unsubscribe/opaque-token-123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The first header is old. RFC 2369, published in July 1998, defined a family of “List-” headers (List-Help, List-Subscribe, List-Unsubscribe, List-Post, List-Owner and List-Archive) so mail programs could offer list commands in a standard way. For List-Unsubscribe, each address goes in angle brackets, several alternatives are separated by commas, and the mail program uses the leftmost one it supports. Back then the expected method was mailto: an email sent to a list manager.

The problem with a plain web link in List-Unsubscribe is that a mail app can’t safely “click” it in the background. Opening the link (an HTTP GET request) might just show a page, and automatic link scanners in spam filters already open links in emails, which could unsubscribe people by accident. RFC 8058 solved this by adding the second header. It tells the mail app: send a POST request to this HTTPS address with this exact body, and the unsubscribe will happen.

What RFC 8058 requires of the sender

RFC 8058 is short, and its rules are specific. Here is what it asks of whoever sends the email (you, through your email provider):

1. Include both headers. The message carries a List-Unsubscribe header and a List-Unsubscribe-Post header.
2. One HTTPS address. List-Unsubscribe “MUST contain one HTTPS URI.” It can also contain other addresses, such as a mailto, alongside it.
3. An exact value. List-Unsubscribe-Post must contain the single key/value pair List-Unsubscribe=One-Click.
4. A link that identifies the reader. The address has to carry enough information to identify the recipient and the list, because the unsubscribe must complete with no further input. The RFC recommends an opaque, hard-to-forge part (a token rather than a plain email address) that your server checks.
5. No cookies, no login, no redirect. The mail app’s POST request must not include cookies or authorization, so your server can’t rely on the reader being logged in. And the sender must not answer with a redirect, because redirected POST requests often fail or turn into GET requests.
6. A DKIM signature that covers both headers. The message needs at least one valid DKIM signature, and both List-Unsubscribe and List-Unsubscribe-Post must be included in that signature. If they aren’t, the RFC says mail apps should not offer one-click unsubscribe for that message.

The DKIM rule is the one that ties this topic to email authentication. If you haven’t set up DKIM for your sending domain yet, start with our guide to SPF, DKIM and DMARC. Without a valid signature covering these headers, the one-click headers are not supposed to be trusted.

On the receiving side, the mail app sends a POST to the HTTPS address with the body List-Unsubscribe=One-Click. The RFC says this can be sent as a form submission (multipart/form-data, or the simpler URL-encoded format). It also says the mail app must not send that request without the reader’s consent, which is why Gmail and others show the option and let the reader choose it rather than unsubscribing anyone automatically. A request from the mail app looks roughly like this:

POST /unsubscribe/opaque-token-123 HTTP/1.1
Host: your-store.example
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

The same address can also serve the familiar web page when someone opens it in a browser (a GET request). The RFC notes that one server address can handle both. What matters is that a POST with that body unsubscribes the reader immediately and returns a success response, with no confirmation page in between.

What Gmail requires

Google’s email sender guidelines split requirements into those for all senders and those for senders of more than 5,000 messages per day to Gmail accounts. For that higher-volume group, Google says marketing messages and subscribed messages “must support one-click unsubscribe” and must include a clearly visible unsubscribe link in the message body. To set up one-click unsubscribe, Google says to include both the List-Unsubscribe-Post and List-Unsubscribe headers in outgoing messages.

Google’s sender guidelines FAQ answers several questions small senders often have:

Google also asks senders to keep the spam rate reported in Postmaster Tools below 0.10% and to avoid ever reaching 0.30% or higher. An easy, reliable unsubscribe is one of the few things you fully control that pushes in the right direction.

What Yahoo requires

Yahoo’s sender best practices ask bulk senders for a functioning List-Unsubscribe header that supports one-click unsubscribe for marketing and subscribed messages. Yahoo says the POST method from RFC 8058 is “highly recommended,” while a mailto address in List-Unsubscribe is still acceptable to Yahoo. In other words, the HTTPS one-click method is the one that satisfies both providers.

Yahoo also asks bulk senders to include a clearly visible unsubscribe link in the email body (it may go to a preference page), to honor unsubscribes within 2 days, and to keep the spam complaint rate below 0.3%.

Gmail, Yahoo and the law, side by side

Mailbox provider rules sit on top of the law, not instead of it. In the United States, the CAN-SPAM Act sets its own opt-out rules, summarized in the FTC’s compliance guide for business. For a fuller checklist, see our CAN-SPAM checklist for online stores; for consent rules in Europe, see GDPR and email marketing consent.

The practical takeaway: aim for the strictest combination. Support the HTTPS one-click headers, keep a visible link in every marketing email, and stop sending to people as soon as they unsubscribe, ideally right away and certainly within two days.

How to check whether your emails have the headers

You don’t need any special tools. Send a real campaign (or a test of it) to a Gmail address you own, then look at the raw message, following Gmail’s instructions for viewing full headers:

1. Open the email in Gmail on a computer.
2. Next to the Reply button, click More, then choose Show original. The full header opens in a new window.
3. Search the raw message for dkim= in the Authentication-Results header and check that it says dkim=pass. One-click depends on a valid DKIM signature.
4. Use your browser’s find feature to search the raw message for List-Unsubscribe. You should see both List-Unsubscribe (with an https:// address in angle brackets) and List-Unsubscribe-Post: List-Unsubscribe=One-Click.
5. Find the DKIM-Signature header and look at its h= list (the headers covered by the signature). Both list-unsubscribe and list-unsubscribe-post should appear there.
6. Check whether Gmail shows its own unsubscribe option near the sender name. If it doesn’t, that isn’t proof of a problem: Google says the option only appears for messages that pass its automated eligibility checks. But if the headers are missing entirely, it won’t appear.

Repeat the check for each tool that sends marketing email for you: your newsletter tool, your store platform’s marketing emails, and any automation tool. They can behave differently, and the headers are added by whichever service actually sends the message.

If you run your own unsubscribe endpoint

Most small stores rely on their email provider for all of this. If you or a developer do build the unsubscribe address yourselves, these are the details that usually go wrong:

One more subtlety: the RFC 8058 security section points out that a successful unsubscribe confirms the address is real. The authors judged this an acceptable risk, since tracking images already reveal the same thing. The opaque token is what keeps third parties from forging requests.

Make the body link easy too

The headers handle the mail app’s option. The footer link still matters, because many readers look there first and both Gmail and Yahoo require a visible link in the body for marketing messages. A few habits make it work well:

1. Make it findable. Use the word “Unsubscribe” and readable contrast. A pale, tiny link might look tidy, but it leads more people to the spam button.
2. Don’t demand a login. The FTC guide says you can’t require more than a reply email or a visit to a single web page, and you can’t ask for personal information beyond an email address.
3. Offer options, but don’t hide the exit. A preference page can let people choose fewer emails or certain topics, but the “unsubscribe from everything” choice should be one obvious click away.
4. Keep links working. Under CAN-SPAM the opt-out must work for at least 30 days after you send, so old campaigns need working links too.
5. Show a clear confirmation. After someone unsubscribes, say so plainly and don’t send a “sorry to see you go” marketing email.

Transactional emails

Order confirmations, shipping notices and password resets are transactional. Google’s FAQ says transactional messages are excluded from the one-click requirement. Two cautions, though. First, the moment a transactional email carries a promotion (“20% off your next order” blocks in a shipping notice), it starts to look like marketing, so keep promotions out of messages that are meant to be purely transactional. Second, adding one-click headers to messages people can’t meaningfully unsubscribe from (a password reset, for example) only confuses readers. Keep the headers for list email.

Where marketingLABO fits, honestly

marketingLABO sends newsletters (Light plan and up) and, on the Standard plan, automated journey emails. Here is what it does and doesn’t do for unsubscribes today:

1. Visible unsubscribe link: yes. The email builder has an Unsubscribe block. When the email is sent, it’s replaced with a link unique to each recipient that takes them to an unsubscribe page.
2. Journeys respect unsubscribes: yes. People who unsubscribe don’t receive the remaining emails in a journey.
3. One-click headers: not yet. We checked our sending code before writing this article: marketingLABO doesn’t currently add the List-Unsubscribe or List-Unsubscribe-Post headers to outgoing emails. That means the mail app’s own one-click option described above won’t be offered from those headers.
4. Sending-domain setup: not in the dashboard. marketingLABO doesn’t have an SPF/DKIM settings screen, so authentication for your own domain is handled with your domain host and the services that send for you.

If you send more than 5,000 marketing emails a day to Gmail addresses, or you need one-click headers for any other reason, use a sending service that adds them, and confirm it with the “Show original” check above. For smaller lists, the visible unsubscribe block plus prompt suppression covers the in-body requirement. See pricing for which plans include newsletters and journeys.

A quick checklist

1. Every marketing email has a visible, readable unsubscribe link in the body.
2. Marketing emails carry List-Unsubscribe with an HTTPS address (a mailto may be added too).
3. They also carry List-Unsubscribe-Post: List-Unsubscribe=One-Click.
4. Both headers are covered by a valid DKIM signature (check the h= list in “Show original”).
5. A POST to the address unsubscribes immediately, with no login, cookie, confirmation step or redirect.
6. The address uses an opaque token, not a plain email address.
7. Unsubscribes take effect right away and well within 2 days, across newsletters and automations.
8. Old campaigns’ links keep working for at least 30 days (CAN-SPAM).
9. Transactional emails stay transactional, without one-click headers or promotions.
10. Spam complaint rate is watched in Google Postmaster Tools and stays below 0.10%.

FAQ

I send fewer than 5,000 emails a day. Do I need one-click unsubscribe?

Google’s one-click requirement is listed for senders of more than 5,000 messages a day to Gmail accounts, and Yahoo’s for bulk senders. Smaller senders aren’t held to the same list, but the same mechanics affect how readers react: an easy exit reduces spam reports. If your provider supports the headers, there’s little reason not to use them.

Is a mailto address in List-Unsubscribe enough?

Not for Gmail. Google’s FAQ says mailto links don’t meet its one-click requirement. Yahoo accepts mailto but highly recommends the RFC 8058 POST method. Including both an HTTPS address and a mailto is allowed by RFC 8058.

Do I still need the unsubscribe link in the footer if I have the headers?

Yes. Both Gmail and Yahoo require a clearly visible unsubscribe link in the body of marketing messages. Google’s FAQ says the body link doesn’t itself have to be one-click when the headers are present.

Why doesn’t Gmail show an unsubscribe option on my emails even though I added the headers?

Google says the option appears only for messages that pass its automated eligibility checks, which include meeting the sender requirements and implementing the headers correctly. Check that DKIM passes and covers both headers, that the address is HTTPS, and that your spam rate is low.

Can I ask people why they’re leaving?

On the page people see after using the footer link, an optional question is fine. It must not be a condition for unsubscribing. The one-click POST should unsubscribe with no questions at all.

Sources

1. RFC 8058, Signaling One-Click Functionality for List Email Headers (accessed October 12, 2026): https://www.rfc-editor.org/rfc/rfc8058
2. RFC 2369, The Use of URLs as Meta-Syntax for Core Mail List Commands and their Transport through Message Header Fields (accessed October 12, 2026): https://www.rfc-editor.org/rfc/rfc2369
3. Google Workspace Admin Help, Email sender guidelines (accessed October 12, 2026): https://support.google.com/a/answer/81126
4. Google Workspace Admin Help, Email sender guidelines FAQ (accessed October 12, 2026): https://support.google.com/a/answer/14229414
5. Gmail Help, Trace an email with its full headers (accessed October 12, 2026): https://support.google.com/mail/answer/29436
6. Yahoo Sender Hub, Sender Best Practices (accessed October 12, 2026): https://senders.yahooinc.com/best-practices/
7. Federal Trade Commission, CAN-SPAM Act: A Compliance Guide for Business (accessed October 12, 2026): https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business