List-Unsubscribe Header Explained: RFC 8058 One-Click Unsubscribe Setup (2026)

List-Unsubscribe Header Explained: RFC 8058 One-Click Unsubscribe Setup (2026)

Photo by Taylor Vick on Unsplash

Quick Answer: The List-Unsubscribe header lets recipients unsubscribe with one click directly from Gmail, Yahoo, and Outlook. RFC 8058 adds the List-Unsubscribe-Post: List-Unsubscribe=One-Click header for true one-click unsubscribes. Google and Yahoo require it for bulk senders (5,000+/day). Setup: add the headers to your email and handle the POST request. Below, the complete guide.

On This Page

• What Is the List-Unsubscribe Header?
• RFC 8058: The One-Click Standard
• How the One-Click Flow Actually Works Under the Hood
• Why It Matters in 2026
• How to Set It Up
• The Unsubscribe Endpoint
• Implementation Examples in Other Languages
• One-Click Support Across Mail Clients
• Monitoring Unsubscribe Behavior After Launch
• Testing Your Setup
• Common Mistakes
• Real-World Scenarios
• Frequently Asked Questions

What Is the List-Unsubscribe Header?

The List-Unsubscribe header is an email header that tells mailbox providers where recipients can unsubscribe without scrolling to the footer.

The header:

List-Unsubscribe: <mailto:unsubscribe@yourdomain.com>, <https://yourdomain.com/unsubscribe>

What it does:

• Gmail shows "Unsubscribe" next to the sender name
• Yahoo and Outlook show it in the menu
• Recipients don't need to find the footer link

The header itself isn't new — it dates back to RFC 2369 in 1998, originally designed for mailing-list software (like majordomo and similar list servers) so mail clients could offer "leave this list" functionality automatically. For most of its history it was mostly used by mail clients to power a small "Unsubscribe" link buried in a menu, and its adoption by mainstream marketing platforms was patchy. What changed everything was Gmail and other major providers surfacing it prominently in the UI — right next to the sender's name at the top of the message — which turned a niche header into one of the most consequential deliverability signals in modern email.

RFC 8058: The One-Click Standard

The Problem With the Original Header

The original List-Unsubscribe required recipients to visit a URL or send an email — multiple steps, friction, and abandonment.

RFC 8058 (2017)

RFC 8058 added a second header for true one-click unsubscribe:

List-Unsubscribe: <https://yourdomain.com/unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

How it works:

1. Recipient clicks "Unsubscribe" in Gmail.
2. Gmail sends a POST request to your unsubscribe URL.
3. Your server unsubscribes them.
4. Recipient sees "Unsubscribed" confirmation.

The Two Headers

The name "RFC 8058" refers specifically to the IETF standards document titled "Signaling One-Click Functionality for List Email Headers," published in November 2017. Its core innovation was recognizing a gap in the older header: a URL alone doesn't tell a mail client how to interact with it safely. If Gmail simply opened the List-Unsubscribe URL in a background GET request without the sender's explicit opt-in, that's dangerous — some legacy unsubscribe links were built to unsubscribe on a simple page load (a GET), which meant automated link-scanners, spam filters, or even email preview/prefetch features could accidentally trigger unintended unsubscribes just by visiting the link, not clicking a button. RFC 8058 solves this by requiring the sender to explicitly declare, via the List-Unsubscribe-Post header, that their endpoint is safe to hit with an automated POST — shifting the "am I sure this won't have destructive side effects on a simple visit" burden from best-effort guessing to an explicit, machine-readable contract.

How the One-Click Flow Actually Works Under the Hood

It's worth walking through exactly what happens end-to-end, because understanding the mechanics makes debugging a broken setup far easier.

1. Your platform sends the message with both headers present in the raw MIME headers (not the body — these are invisible to the recipient when they open the email normally).
2. The receiving mail client parses the headers when the message arrives or when the user opens it. Gmail, Yahoo Mail, and Outlook.com all specifically look for the combination of List-Unsubscribe (with an https:// URL — a bare mailto: alone does not trigger one-click) and List-Unsubscribe-Post with the exact value List-Unsubscribe=One-Click.
3. If both are present and well-formed, the client renders a native "Unsubscribe" affordance — for Gmail, this appears as clickable text next to the sender's name in the message list and inside the opened message; for Outlook, it typically appears in a dropdown near the sender.
4. When the recipient clicks it, the mail client itself — not the recipient's browser — issues the HTTP POST request directly to the URL in your List-Unsubscribe header, with the body List-Unsubscribe=One-Click and content type application/x-www-form-urlencoded. This is a server-to-server request from Google's or Microsoft's infrastructure to yours; the recipient's own device may not even be the one making the network call, depending on the client.
5. Your server must process the request and respond within a short timeout window (Google's documentation has historically indicated requests should be handled promptly, generally expecting a response in a few seconds) with an HTTP success status. If your endpoint times out, errors, or requires authentication, the mail client will typically show the recipient a generic failure, and — worse for you — some clients cache the fact that unsubscribing failed and won't retry automatically.
6. The mail client shows a confirmation (often something like "You have been unsubscribed from this mailing list. It might take a few days before you stop receiving these emails.") without ever navigating the recipient to your website. This confirmation is generated by the mail client itself, not your server's response body — this is a common point of confusion, since your endpoint's actual response content is essentially irrelevant to what the recipient sees, only the HTTP status matters.

This last point matters for implementation: because the client-rendered confirmation doesn't reflect your response body, you cannot use this endpoint to show custom messaging, a preference center, or a "sorry to see you go" survey — the one-click flow is intentionally frictionless and opaque. If you want to offer a preference center (e.g., "reduce frequency" instead of a full unsubscribe), that has to live at the separate, human-clickable footer link, not the RFC 8058 endpoint.

Why It Matters in 2026

Google & Yahoo Requirements

Since 2024, Google and Yahoo require one-click unsubscribe for bulk senders (5,000+ emails/day):

The Benefits

The complaint-rate connection deserves unpacking, because it's the real mechanism behind why this header affects deliverability so directly. From a recipient's perspective, "Report spam" and "Unsubscribe" solve the same underlying problem — "I don't want this in my inbox anymore" — but they have very different consequences for the sender. A complaint (spam report) is a strongly negative reputation signal that mailbox providers weigh heavily when deciding how to filter your future mail; an unsubscribe is a neutral, expected part of normal list hygiene that carries no reputation penalty at all. When the unsubscribe path is buried, slow, or requires multiple steps (finding the footer, clicking through, confirming, maybe even logging in), a meaningful fraction of recipients who would have happily unsubscribed instead take the path of least resistance sitting right in their inbox toolbar: hit "Report spam." Every one of those clicks nudges your complaint rate upward, and Gmail and Yahoo's published thresholds for acceptable spam-complaint rates (widely cited as needing to stay under roughly 0.3%, with rates above 0.1% already considered a warning sign) exist precisely because complaint rate is one of the strongest predictors receiving infrastructure uses to decide whether your domain's mail belongs in the inbox, the spam folder, or gets throttled/blocked outright.

Photo by Mariia Shalabaieva on Unsplash

How to Set It Up

Option 1: Use Your Email Platform

Most email platforms (MisarMail, Brevo, MailerLite) add the headers automatically:

1. Enable one-click unsubscribe in your platform settings.
2. Verify the headers appear in test emails.
3. Confirm the unsubscribe endpoint is handled.

Option 2: Add Headers Manually

If you send via your own SMTP/API:

List-Unsubscribe: <https://yourdomain.com/unsubscribe?email={{email}}&token={{token}}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Option 3: mailto Fallback

For non-HTTP setups:

List-Unsubscribe: <mailto:unsubscribe@yourdomain.com?subject=unsubscribe>

Note: mailto alone doesn't support one-click. Use HTTPS for RFC 8058 compliance.

Combining mailto and HTTPS

You can actually include both a mailto: and an https: option in the same header, comma-separated, giving mail clients that don't support one-click POST a fallback path:

List-Unsubscribe: <mailto:unsubscribe@yourdomain.com>, <https://yourdomain.com/unsubscribe?email={{email}}&token={{token}}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Clients that support RFC 8058 will use the HTTPS URL with the POST flow; clients that only support the older header will fall back to composing a mailto message. This belt-and-suspenders approach is common among ESPs precisely because not every mail client in the world has adopted the one-click standard, even though the three largest consumer providers (Gmail, Yahoo, Outlook.com) all support it.

The Unsubscribe Endpoint

The Requirements

The Implementation (Node.js)

app.post('/unsubscribe', async (req, res) => {
  const { email, token } = req.query;

  // Verify token
  if (!verifyToken(email, token)) {
    return res.status(400).send('Invalid token');
  }

  // Unsubscribe
  await db.update({ email }, { subscribed: false });

  // Respond 200 immediately
  res.status(200).send('OK');
});

The Security Considerations

• Tokenize the unsubscribe URL (don't rely on email alone)
• Rate limit the endpoint
• Log unsubscribe requests
• Handle GET requests too (some clients use GET)

Tokenization deserves special emphasis. If your unsubscribe URL is just https://yourdomain.com/unsubscribe?email=someone@example.com with no token, anyone who can guess or enumerate an email address can unsubscribe any recipient from your list without their consent — a malicious actor could scrape your list of subscribers (or simply guess common addresses) and mass-unsubscribe your entire audience, silently killing your list growth. The token should be a per-recipient, non-guessable value (commonly an HMAC of the email address plus a secret key, or a random value stored against that subscriber in your database) that proves the link genuinely originated from an email you sent to that specific person, not something a third party constructed.

On idempotency: because mail clients may retry a failed POST, or because a recipient might click the link more than once out of confusion, your endpoint needs to handle "unsubscribe a person who is already unsubscribed" gracefully — returning the same 200 OK rather than erroring out. This is a small implementation detail that's easy to overlook but causes real support headaches (and occasionally, a recipient who keeps receiving mail because a retried request hit an error path that never actually processed the unsubscribe) if missed.

On the "handle GET requests too" point: while RFC 8058 specifies POST, some older or non-compliant clients (or preview/scanning tools) still issue a GET to the same URL. A common defensive pattern is to have GET requests to the unsubscribe endpoint render a simple confirmation page with a "Click to confirm unsubscribe" button (so a GET alone — which could come from an automated scanner rather than genuine recipient intent — doesn't silently unsubscribe someone) while POST requests process immediately per the one-click contract, since POST specifically signals genuine client-initiated action per RFC 8058's design.

Implementation Examples in Other Languages

Python (Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route('/unsubscribe', methods=['POST'])
def unsubscribe():
    email = request.args.get('email')
    token = request.args.get('token')

    if not verify_token(email, token):
        return 'Invalid token', 400

    mark_unsubscribed(email)
    return 'OK', 200

PHP

<?php
$email = $_GET['email'] ?? null;
$token = $_GET['token'] ?? null;

if (!$email || !$token || !verify_token($email, $token)) {
    http_response_code(400);
    exit('Invalid token');
}

mark_unsubscribed($email);
http_response_code(200);
echo 'OK';

Both examples follow the same shape as the Node.js version: verify a per-recipient token, mark the subscriber as unsubscribed in your database, and respond quickly with a 2xx status — the specific framework matters far less than getting those three steps right and keeping the response time low, since mail-client-initiated POST requests are not tolerant of slow backends.

One-Click Support Across Mail Clients

Not every mail client implements RFC 8058 identically, which is worth knowing when you're debugging why the button looks different (or doesn't appear at all) in different inboxes.

Because coverage isn't universal, the practical takeaway is the same one from the mailto/HTTPS fallback section above: implement RFC 8058 fully for the clients that support it (which covers the large majority of consumer inbox share), but don't remove the traditional, human-clickable footer unsubscribe link — it remains the fallback for any client, plugin, or edge case that doesn't recognize the one-click headers.

Monitoring Unsubscribe Behavior After Launch

Once the headers are live, it's worth tracking a few signals over the following weeks to confirm the change is having the intended effect rather than just assuming it works:

• Unsubscribe rate trend. A short-term bump right after launch is normal and healthy — you're making it easier for people who already wanted to leave to actually do so, which is a sign the feature is working, not a problem to fix.
• Spam complaint rate trend. This is the metric that should trend downward over the following sending cycles, since the entire mechanism of RFC 8058's deliverability benefit is diverting "I don't want this" clicks away from the spam button and toward unsubscribe.
• Endpoint error rate and latency. Since the one-click POST is machine-initiated by the mail provider's own infrastructure rather than a human browsing your site, ordinary web monitoring (uptime checks, response-time alerts) should be pointed at this endpoint specifically — a silent failure here has no human in the loop to notice and report it the way a broken checkout page would.
• Postmaster Tools compliance signals. Google Postmaster Tools surfaces domain reputation and spam-rate data that indirectly reflects whether your unsubscribe mechanics are working as intended; a persistently elevated spam rate despite a compliant one-click setup is a sign the problem lies elsewhere (content, frequency, list quality) rather than in the unsubscribe implementation itself.

Testing Your Setup

The Test Checklist

• [ ] Headers present in raw email source
• [ ] List-Unsubscribe-Post header included
• [ ] POST request returns 200
• [ ] Unsubscribe processes within 2 days
• [ ] Works in Gmail (one-click)
• [ ] Works in Yahoo (one-click)
• [ ] Works in Outlook (menu)
• [ ] Footer unsubscribe still works

How to Test

1. Send a test email to Gmail.
2. Open the email → three dots → "Show original."
3. Check for List-Unsubscribe and List-Unsubscribe-Post.
4. Click "Unsubscribe" in Gmail's interface.
5. Verify you're unsubscribed.

The Validation Tools

A subtlety worth testing explicitly: some mail clients cache their evaluation of whether a sender supports one-click unsubscribe, meaning if your very first test send was missing the header (or malformed), the client might not immediately pick up a corrected header on your next send to the same test inbox. When in doubt, test with a fresh recipient address you haven't sent to before, to rule out client-side caching as a false negative.

Common Mistakes

Only including a mailto: link, with no HTTPS URL. Without an https:// URL and the List-Unsubscribe-Post header, Gmail and Yahoo will not offer true one-click unsubscribe — a bare mailto fallback still requires the recipient to compose and send an email, which defeats the purpose and won't satisfy the 2024+ bulk sender requirements.

Forgetting the List-Unsubscribe-Post header entirely. Some senders add List-Unsubscribe with an HTTPS URL but never add the companion header, not realizing both are required together for the one-click behavior to activate. Without it, mail clients may still show a generic unsubscribe link, but it typically opens the URL in a browser rather than triggering the frictionless one-click POST flow.

Building an unsubscribe endpoint that requires login or a CAPTCHA. Both of these directly violate the "no login, no CAPTCHA" requirement, and practically speaking, a CAPTCHA on a machine-to-machine POST request from a mail provider's infrastructure will simply always fail, since there's no human present at that point in the flow to solve it.

Slow database writes blocking the HTTP response. If your unsubscribe handler does something expensive synchronously (sending a confirmation email, triggering a CRM webhook, recalculating segment membership) before responding, you risk the request timing out from the mail client's perspective. Mark the subscriber unsubscribed and respond immediately; push slower follow-up work (analytics, notifications) to an async queue rather than doing it inline.

Not distinguishing GET from POST at the endpoint, and unsubscribing on any request. As discussed above, this creates a real risk of accidental unsubscribes from automated link scanners or security scanning tools that a company's own IT department might run against inbound/outbound mail.

Un-tokenized unsubscribe links. Covered in detail above — this is a genuine security and list-integrity risk, not just a theoretical one.

Real-World Scenarios

A SaaS company sending a weekly product newsletter to 50,000 subscribers. This is squarely in Google/Yahoo bulk-sender territory even without hitting the 5,000/day threshold on any single day (the requirement is generally evaluated based on aggregate volume patterns to a given provider), so RFC 8058 compliance isn't optional here — it's foundational. The company should verify their ESP has one-click enabled by default and periodically re-test with a fresh Gmail account, since header compliance can silently regress after a platform migration or template change.

An e-commerce store that wants to offer a "pause emails for 30 days" option instead of a full unsubscribe. Because the one-click POST flow can't render custom UI or options, this kind of granular preference needs to live behind the traditional footer link (which can open a preference-center webpage with multiple choices), while the RFC 8058 header still points to a straightforward, no-questions-asked full unsubscribe. Trying to redirect the one-click flow into a preference center instead of an immediate unsubscribe is a common mistake — it violates the spirit (and often the practical requirement) of "no additional steps."

A niche newsletter sent by a solo creator to under 1,000 subscribers, well under the bulk-sender threshold. Not legally/contractually required to implement RFC 8058, but still worth doing — the deliverability and reduced-complaint benefits apply regardless of volume, and most modern sending platforms (including MisarMail) add the headers automatically at no extra effort, so there's little reason to skip it even at small scale.

Related Reads

• Google & Yahoo Bulk Sender Requirements 2026: The Complete Compliance Checklist
• What Is BIMI and How to Set It Up (2026 Guide)
• DMARC Enforcement 2026: How to Move From p=none to p=reject Safely