Deliverability

How to check one-click unsubscribe (RFC 8058) headers

TL;DR

Open the raw source of a delivered issue and look for two headers: List-Unsubscribe with an HTTPS URI, and List-Unsubscribe-Post set to the literal value List-Unsubscribe=One-Click. Both must be named in your DKIM signature's h= tag, and the endpoint must answer a bare POST without redirecting. Four of the eight ESP help centers we read promise that pair in writing. The other four leave you to verify it yourself.

Gmail and Yahoo have required one-click unsubscribe from bulk senders since February 2024, and every major platform published a reassuring announcement within weeks. An announcement is not a header. The only way to know what mailbox providers see is to check the one-click unsubscribe headers in a message that really delivered, and that check takes five minutes with nothing but your inbox and a terminal. While building the header parser inside Newsletrix we read RFC 8058 and eight ESP help centers side by side, and the gap between what platforms announced and what their documentation commits to is wider than you would expect.

Check the one-click unsubscribe headers in five minutes

In Gmail, open a delivered issue, click the three-dot menu and choose Show original. In Outlook.com the same thing is View message source. Search the page for List-Unsubscribe. A compliant message carries this pair:

List-Unsubscribe: <https://news.example.com/u/abc123>, <mailto:[email protected]>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The wording in RFC 8058 is strict on both lines. The List-Unsubscribe header field MUST contain one HTTPS URI; a mailto address may ride along, but it cannot stand alone. And List-Unsubscribe-Post MUST contain the single key/value pair List-Unsubscribe=One-Click. That value is a literal, not a convention. A homegrown sender that emits One-click or OneClick has shipped a header that no mailbox provider will act on.

One warning before you start: test sends lie. Beehiiv's support docs say the header is injected into published posts and is absent from test emails, so mailing yourself a preview proves nothing. Send a real campaign to a seed address and read that copy. The same headers feed Gmail's subscription manager, which we covered in our guide to the Manage subscriptions pane.

Three failure modes that look fine from the footer

Your footer link can be perfect while the headers fail. These are the three patterns worth hunting for, and your footer itself has its own rules, which we collected in the footer compliance checklist and automated in the footer checker.

First, the mailto-only header. Plenty of older transactional setups set List-Unsubscribe: <mailto:[email protected]> and nothing else. That was respectable in 2019. Under RFC 8058 there is no HTTPS URI to POST to, so there is no one-click, and Google's sender guidelines show the HTTPS form in their own example.

Second, a missing or mangled List-Unsubscribe-Post. The first header without the second is plain list-unsubscribe, a 1998 mechanism that providers treat with suspicion because a GET can be replayed by every link scanner between you and the inbox. SendGrid's documentation is blunt about this: anti-spam software follows links, so nothing should be unsubscribed on a GET. The POST header is what separates a deliberate human action from a bot crawl.

Third, the two-click body link mistaken for compliance. Mailchimp's help page describes a confirmation page after the footer click, two clicks in total, and defends it as protection against accidental opt-outs. The same page says this flow does not affect the one-click process available through the email headers. Both statements are true, and neither one tells you whether your campaign carried the headers. Google requires both things separately for senders over 5,000 messages a day: one-click unsubscribe support and a clearly visible unsubscribe link in the body. The full list of those requirements is in our bulk sender requirements breakdown.

A working pair will raise your unsubscribe count in week one. That is the point. Every one of those exits was a reader who would otherwise drift toward the spam button, and Google tells senders to hold user-reported spam below 0.10% and never reach 0.30%. An unsubscribe costs you a subscriber. A complaint costs you the list.

Replay the one-click unsubscribe POST with curl

When a reader confirms the unsubscribe prompt, Gmail does not open your landing page. It sends an HTTPS POST to the URI from your List-Unsubscribe header with the body List-Unsubscribe=One-Click. You can replay that request exactly:

curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" --data "List-Unsubscribe=One-Click" "https://news.example.com/u/abc123"

Careful: this is live ammunition. The token in that URI identifies a subscriber, and a compliant endpoint will remove them. Run it against your own seed subscription, never a URI copied from someone else's mail.

RFC 8058 spells out what the endpoint owes you back. The sender MUST NOT return an HTTPS redirect, because redirected POSTs historically turn into GETs. The request arrives with no cookies and no authorization context, so the endpoint cannot hide behind a login. And the whole mechanism exists so that software never has to interpret a confirmation page. In practice that means you want a 2xx within a few seconds and a subscriber record that flips on that request alone. Google's sender FAQ recommends fulfilling unsubscribe requests within 48 hours, and its enforcement table withholds delivery support and mitigation from senders who miss that window.

The DKIM h= tag check nobody runs

This is the step that explains most ghost failures. RFC 8058 requires the message to carry a valid DKIM signature that covers both unsubscribe headers, named in the h= tag of the DKIM-Signature header, and it tells receivers not to offer one-click when that coverage is missing. Header present, button absent, and nobody knows why: the h= tag is usually why.

In the same raw source, find DKIM-Signature and read the h= list. You want to see both names in there, something like h=from:to:subject:list-unsubscribe:list-unsubscribe-post:mime-version. If your platform signs From and Subject but not the unsubscribe pair, an intermediary can swap your unsubscribe URI for theirs, which is exactly the forgery the RFC is guarding against. Reading signatures is a skill worth having anyway; we walk through the related Gmail labels in mailed-by, signed-by and via and the wider setup in our SPF, DKIM and DMARC explainer.

Even a signed, correct pair does not guarantee the button. Google's sender guidelines FAQ says the unsubscribe link appears only for messages that pass its automated eligibility checks, and it names correct headers, gradual volume growth and low spam reports as the inputs. So treat the button as a lagging indicator of trust, and the headers as the part you control.

What eight ESP help centers put in writing

We went looking for one sentence in each help center: we add the one-click headers for you. Four platforms say it plainly, one makes it conditional on a setting, and three never quite say it. Documentation checked November 2026; every claim below links to its source.

PlatformWhat the docs commit to
KlaviyoAdds the one-click header code to every email automatically; no action needed for the Google and Yahoo rules.
BrevoIncludes List-Unsubscribe on campaigns and transactional email by default; Enterprise plans can swap transactional mail to a List-Help header instead.
BeehiivInjects the header into published posts; the docs note it is absent from test emails.
PostmarkAdds both headers on Broadcast message streams automatically; on transactional streams they are optional and honored if you set them.
SendGridInserts the pair when subscription tracking is enabled; otherwise you set both headers yourself via the v3 API or SMTP.
MailchimpDescribes header-based one-click and defends the two-click footer flow, but never states outright that it adds the headers for you.
SubstackNo public documentation of the headers that we could find.
KitNo public documentation of the headers that we could find.

Our position: trust headers, not help centers. A platform that documents the behaviour hands you something to quote in a support ticket. A platform that does not leaves your deliverability resting on a forum answer, however good the engineering underneath may be. Either way the raw source of a delivered message outranks every page in the table above, including this one.

The unsubscribe domain is a fingerprint

We parse List-Unsubscribe inside Newsletrix for a different reason than compliance: it is one of the hardest headers for a platform to disguise. When a sender strips the obvious vendor headers, the unsubscribe URI still points at mailchimp.com, sendgrid.net, klaviyomail.com, hubspotemail.net or createsend.com, and our detection code treats that domain as a medium-confidence platform match after the high-confidence vendor headers come up empty. White-label setups cover the sending domain far more often than they cover the unsubscribe endpoint. When that domain changes between two issues, the brand almost always switched ESP.

To be clear about scope: our pipeline reads List-Unsubscribe to identify the platform. It does not parse List-Unsubscribe-Post and it does not judge RFC 8058 compliance, so the five-minute check above is still yours to run. We would rather say that plainly than imply a feature we have not built.

Find the platform behind any newsletter

The ESP detector explains how Newsletrix identifies 30+ sending platforms from headers like List-Unsubscribe, Return-Path and Message-ID, and the tracker runs that detection on every newsletter it follows.

See how ESP detection works →

Make the check part of the send routine

Before the next issue goes out: deliver a live campaign to a seed Gmail address, open Show original, read the pair, read the h= tag, then curl the POST from a disposable subscription of your own. Five minutes, once per ESP migration and once per quarter. If anything is missing, your support ticket writes itself, and the documentation links in the table are your citations. If you also want rendering previews and broader pre-send testing, that is a different tool category, and our Litmus comparison covers where those products end and competitive newsletter tracking begins.

The senders who get burned by the bulk rules are rarely the ones ignoring them. They are the ones who read the announcement, saw their platform's name on a compliance list and never looked at a delivered message. Reading two headers is the cheapest deliverability audit you will run this year.

Frequently asked questions

Does a mailto-only List-Unsubscribe header satisfy Gmail's one-click requirement?

No. RFC 8058 requires one HTTPS URI in the List-Unsubscribe header, and Gmail's one-click flow is an HTTPS POST to that URI. A mailto address may sit alongside the HTTPS URI, but on its own it gives the mailbox provider nothing to POST to.

How do I test List-Unsubscribe-Post with curl?

Copy the HTTPS URI out of your List-Unsubscribe header and send it a POST with curl, using a Content-Type of application/x-www-form-urlencoded and the exact body List-Unsubscribe=One-Click. A compliant endpoint answers with a 2xx status, no redirect and no login wall. The POST really unsubscribes the address behind that token, so run it against your own seed subscription.

Why does Gmail not show the unsubscribe button even though my headers exist?

Google's sender guidelines FAQ says the link appears only for messages that pass its automated eligibility checks, which include correct one-click headers, gradual sending volume and low spam reports. The most common silent failure is a DKIM signature whose h= tag does not cover the two unsubscribe headers; RFC 8058 tells receivers not to offer one-click in that case.

Does DKIM need to sign the List-Unsubscribe headers?

Yes. RFC 8058 requires both List-Unsubscribe and List-Unsubscribe-Post to be covered by a valid DKIM signature and named in its h= tag. Open the raw source of a delivered message, find the DKIM-Signature header and check that both header names appear in the h= list.

Is Mailchimp's unsubscribe link one-click compliant?

The footer link is not one-click by design. Mailchimp's help pages describe a confirmation page, so opting out through the email body takes two clicks, and Mailchimp states this flow does not affect the header-based one-click process Gmail and Yahoo use. Its documentation stops short of saying the headers are added automatically, so check a delivered campaign's raw source.

Related reading

Get started

Stop guessing. Start winning.

Join newsletter creators using AI-powered competitor intelligence to ship better content, faster.

No credit card required  ·  Cancel anytime  ·  All features on every plan