Guide
The List-Unsubscribe header tells a recipient's mailbox provider how to unsubscribe someone from a mailing list. When it is present, providers like Gmail and Yahoo show a native unsubscribe button at the top of the message, next to the sender name, separate from any link in the message body. RFC 8058 adds a second header that makes that button work in a single action, with no landing page and no login.
Last reviewed September 2026
One-click unsubscribe is not a single header. It is two, and a message carrying only the first does not qualify.
List-Unsubscribe carries the unsubscribe destination. It is the older of the two, defined in RFC 2369 back in 1998, and it accepts one or more URIs in angle brackets: historically a mailto: address, and since RFC 8058 at least one HTTPS URL. To comply with RFC 8058 the header must contain at least one HTTPS URI. A mailto: may be listed alongside it, and several senders list both so that older clients still have something to act on.
List-Unsubscribe-Post is the signal that the HTTPS URL will accept a one-click POST. Its value is always the same literal string, List-Unsubscribe=One-Click. There are no other valid values, and the header carries no other information. Its only job is to tell the mailbox provider that the endpoint on the other end is safe to POST to without asking the recipient anything further.
List-Unsubscribe: <https://example.com/u/9f3a2c>, <mailto:unsub@example.com?subject=9f3a2c>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickWhen the recipient presses the native unsubscribe button, the provider issues an HTTPS POST to the URL from the first header, with the same literal string as the request body:
POST /u/9f3a2c HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-ClickThat is the whole exchange. No landing page, no login, no preference center. The recipient leaves the list in a single action, where a footer link requires them to click through and then find their way through whatever page is waiting on the other side. The endpoint should return a success response and treat the request as final: the provider will not send the recipient anywhere to confirm it.
RFC 8058, "Signaling One-Click Functionality for List Email Headers", was published in January 2017. That is worth stating plainly, because the standard is routinely described as a response to the Google and Yahoo bulk sender rules. It predates them by seven years. What changed in 2024 was not the specification but its enforcement.
The specification is short, and its substantive requirements are these:
List-Unsubscribe header must contain at least one HTTPS URI.List-Unsubscribe-Post: List-Unsubscribe=One-Click.The POST requirement is the part most guides state without explaining, and it is the part worth understanding, because the reasoning generalizes well beyond unsubscribes.
Security gateways and link scanners follow the links in a message to check them for malware and phishing. That is their job, and the check happens before the recipient ever sees the message. A GET-based unsubscribe URL is an ordinary link as far as that infrastructure is concerned, so it gets fetched, and fetching it performs the unsubscribe. The recipient never asked for anything and never even opened the message, and they are off the list.
Requiring a POST closes that path. An automated fetch that follows links cannot complete a POST with the right body by accident, so the scanner checks the URL and moves on without triggering the action behind it.
Security vendors do make an effort to recognize unsubscribe and opt-in links and leave them alone. They get it wrong regularly, and in practice both link types are clicked by automated systems every day. That is the failure RFC 8058's POST requirement exists to defend against, and it is a concrete illustration of why Non-Human Interactions are an operational problem rather than only a reporting one. An inflated click rate is a bad number. An automated unsubscribe is a lost recipient.
RFC 8058 protects the unsubscribe end of the subscription lifecycle by requiring a POST. Nothing protects the other end.
Double opt-in confirmation links are almost always plain GET URLs. The recipient receives a "confirm your subscription" message, clicks the link, and the click records the consent. The same scanning infrastructure that would follow a GET-based unsubscribe URL follows that confirmation URL too, for exactly the same reason, and confirms a subscription nobody asked for.
The consequences are worse than a false unsubscribe, because a false unsubscribe loses you a recipient while a false confirmation gives you a record that says something untrue:
The link in the confirmation message should open a page, and that page should require a deliberate action before the opt-in is recorded. A checkbox and a submit button, a CAPTCHA and a confirm button, or any equivalent interaction that an automated fetch cannot complete.
Stated as a rule: a GET request should render a confirmation page, and only a subsequent POST from that page should record the consent. It is the same principle RFC 8058 applies to unsubscribes, applied to the opposite end of the lifecycle. Log what the POST tells you, including the timestamp and the request details, and you have a consent record that means something.
The full treatment of the confirmation side, including what to log and which defenses do not work, is in the double opt-in guide. Opt-in and opt-out are the same problem seen from two ends: RFC 8058 protects one of them and nothing protects the other.
The asymmetry is worth saying out loud. The standards body mandated protection for opting out, and nothing comparable exists for opting in, even though the compliance exposure on the opt-in side is larger.
All three now require an unsubscribe mechanism from bulk senders, and all three are frequently reported as requiring the same thing. They do not. The differences are small, but they decide whether a given implementation passes.
Google's guidelines cover senders of more than 5,000 messages per day to personal Gmail accounts. Mail to Google Workspace accounts is not counted toward that threshold and is governed separately, which is a qualifier that matters for B2B programs: a sender whose list is mostly corporate Workspace addresses may sit under the threshold on Google's count while looking well over it on their own.
Microsoft's requirements apply to senders of more than 5,000 messages per day to its consumer domains, outlook.com, hotmail.com and live.com. Yahoo publishes no numeric threshold and states its requirements for bulk senders generally.
Google is the hardest of the three. Its sender guidelines state that marketing messages and subscribed messages must support one-click unsubscribe and include a clearly visible unsubscribe link in the message body, and its subscription guidelines require senders to process and honor unsubscribe requests within 48 hours. The implementation deadline for one-click unsubscribe was 1 June 2024.
Yahoo is worded more loosely than it is usually reported. Its sender FAQ says senders must implement the list-unsubscribe header, "preferably according to RFC 8058", and its best practices page describes the POST method as "highly recommended" rather than mandatory. Yahoo is specific about timing: unsubscribes must be honored within two days, and an unsubscribe not honored within two days does not meet the requirement.
Microsoft is the least prescriptive. Its requirements for high-volume senders, announced in April 2025 and enforced from 5 May 2025, mandate SPF, DKIM and DMARC, along with a functional and clearly visible way to opt out. One-click unsubscribe under RFC 8058 is supported and recommended, not mandated, so a sender who fails RFC 8058 alone is not thereby non-compliant with Microsoft.
The common flattening of all this into "Google, Yahoo and Microsoft all require RFC 8058" is wrong in two directions at once. Yahoo and Microsoft both stop short of mandating it, and Google mandates one-click unsubscribe rather than the RFC by name, though in practice the two headers are how you satisfy Google.
Enforcement has tightened steadily. Microsoft began rejecting mail that fails its authentication requirements at the SMTP level in May 2025, returning 550 5.7.515 rather than routing to the junk folder as originally announced. Google moved from filtering to rejection during November 2025, escalating from temporary failures to permanent ones for traffic that does not meet the requirements. The practical shift is that a non-compliant message is no longer a message in the spam folder. It is a message that was never delivered.
One-click unsubscribe arrived as part of a package, and the rest of the package is authentication and complaint rate: SPF and DKIM on the sending domain, DMARC at a minimum of p=none with alignment to one of them, and a spam complaint rate below 0.30% as reported in Google Postmaster Tools. Treat 0.10% as the number to manage against rather than 0.30%, which is the point at which delivery is already suffering. Those are covered properly on the deliverability page rather than here.
Order confirmations, password resets, one-time passwords and shipping notifications are outside the unsubscribe requirements at all three providers. Google draws the line at messages sent for legal reasons or in response to an explicit action by the user; Yahoo states the requirement applies to promotional and marketing messages and not to transactional ones. That exemption is not a loophole to route marketing through, and the next section covers why you should take it seriously in the other direction as well.
Side by side
The three sets of requirements overlap but do not match. Where a provider does not publish a figure, this table says so rather than borrowing one from another provider.
| Yahoo | Microsoft | ||
|---|---|---|---|
| Applies to | More than 5,000 messages per day to personal Gmail accounts | Bulk senders; no numeric threshold published | More than 5,000 messages per day to outlook.com, hotmail.com and live.com |
| Google Workspace / business mailboxes counted | No - personal Gmail accounts only | Not specified | No - consumer domains only |
| One-click unsubscribe | Required for marketing and subscribed messages | Required; RFC 8058 POST method "highly recommended" | Supported and recommended, not mandated |
| RFC 8058 named as mandatory | No - one-click unsubscribe is mandated, RFC 8058 is how you implement it | No - "preferably according to RFC 8058" | No |
| Visible unsubscribe link in the message body | Required | Required | Required |
| Deadline to honor a request | 48 hours | 2 days | Not specified |
| Transactional mail | Exempt | Exempt | Exempt |
| SPF and DKIM | Both required | Both required | Both required |
| DMARC | Required, p=none minimum, aligned with SPF or DKIM | Required, p=none minimum | Required, p=none minimum, aligned with SPF or DKIM |
| Published spam rate ceiling | Below 0.30% in Postmaster Tools | Below 0.30% | No numeric threshold published |
| In force since | 1 June 2024 for one-click unsubscribe | June 2024 | 5 May 2025 |
Sources: Google, "Email sender guidelines" and "Email subscription guidelines for senders"; Yahoo Sender Hub best practices and sender FAQ; Microsoft, "Strengthening Email Ecosystem: Outlook's New Requirements for High-Volume Senders", April 2025. Checked September 2026. All three providers revise these pages, so confirm against the current version before relying on a specific figure.
Every provider exempts transactional mail from the unsubscribe requirement. Most guides stop there, as though the exemption were merely permission to skip some work. It is stronger than that: adding the header to transactional mail is an error, not an optional extra.
There is nothing to unsubscribe from. A password reset, a one-time passcode or a fraud alert is not a subscription. Offering the recipient a way out of it is incoherent, and honoring such a request could lock someone out of their own account. An unsubscribe control that you cannot act on is worse than no control at all, because the recipient reasonably expects it to do something.
It confuses the categorization your sending is judged on. Mailbox providers assess streams, not individual messages. Marketing headers on transactional mail push that traffic toward the bulk classification, which is assessed against complaint rates and engagement patterns that transactional mail was never going to produce. The stream that most needs to reach the inbox ends up measured by the wrong yardstick.
The right header for transactional mail is List-Help. It points the recipient at support rather than at an opt-out, which is the thing they actually want when a receipt looks wrong or a reset code has not arrived. It carries the same "this sender is well configured" signal without claiming the message is a subscription.
Omnivery sets List-Unsubscribe automatically on marketing messages and never on transactional messages, where it sets List-Help instead. The categorization is applied by the platform rather than left to the sending system to get right, which is deliberate: the mistake is easy to make in application code and invisible until a filtering decision surfaces it months later.
Almost every failure here is partial compliance rather than none. The sender believes the requirement is met, the header is present, and something one layer down does not work. In order of how often they turn up:
List-Unsubscribe present, List-Unsubscribe-Post missing. The most common near-miss. Without the second header the provider has no signal that the URL is safe to POST to, so no native one-click button appears and the sender fails the requirement while looking compliant in their own message source.mailto: URI with no HTTPS URI. Valid under the older RFC 2369, and not enough for RFC 8058. The HTTPS URI is what one-click runs on.The check that catches most of these takes a minute: send yourself a message, open the raw source, confirm both headers are present with an HTTPS URI, then POST to that URL from the command line with the body List-Unsubscribe=One-Click and confirm the address is actually suppressed on the next send.
In practice
Header handling is applied by the platform rather than left to the sending system, so a campaign leaving an older tool still meets the current requirements. The full headers table, including every option below, is in the sending documentation.
List-Unsubscribe and List-Unsubscribe-Post are set automatically on marketing messages, per RFC 8058, whether or not the platform above Omnivery emits them.List-Unsubscribe at submission, Omnivery substitutes its own unsubscribe URL and redirects to the supplied URL on GET requests. Unsubscribes are always honored in Omnivery's own suppression state, and the customer's existing unsubscribe flow is preserved.List-Help is set on transactional messages instead of List-Unsubscribe, so a receipt or a password reset never offers an opt-out it cannot act on.Message-Category is set to bulk/newsletter for marketing and transaction/commercial for transactional, and Precedence: bulk is applied to marketing only.X-CSA-Complaints, X-Complaints-To and Abuse-Reports-To. CSA is the Certified Senders Alliance.At a glance
Questions
The List-Unsubscribe header is an email header that tells the recipient's mailbox provider how to unsubscribe someone from a mailing list. When it is present, providers like Gmail and Yahoo display a native unsubscribe button at the top of the message, next to the sender name, separate from any unsubscribe link in the message body. It was defined in RFC 2369 in 1998 and originally carried a mailto: address; RFC 8058 later required an HTTPS URI so the unsubscribe could be completed in one click.
RFC 8058, "Signaling One-Click Functionality for List Email Headers", is the 2017 specification that defines one-click unsubscribe. It requires the List-Unsubscribe header to contain at least one HTTPS URI, adds a second header, List-Unsubscribe-Post, with the fixed value List-Unsubscribe=One-Click, and requires that the URI accept an HTTP POST which completes the unsubscribe with no further interaction from the recipient. It predates the Google and Yahoo bulk sender requirements by seven years.
List-Unsubscribe carries the destination: one or more URIs, at least one of which must be an HTTPS URL for RFC 8058 compliance. List-Unsubscribe-Post carries no information at all beyond a fixed signal, the literal value List-Unsubscribe=One-Click, which tells the mailbox provider that the HTTPS URL will accept a one-click POST. Both headers must be present. A message carrying only List-Unsubscribe does not get a one-click unsubscribe button.
Yes. The two are separate requirements and both are required. Google, Yahoo and Microsoft all require a clearly visible unsubscribe link in the message body, and Google and Yahoo additionally require the list-unsubscribe header for marketing and subscribed messages. A footer link does not satisfy the header requirement, and the header does not remove the need for the visible link.
No. Transactional messages are exempt at all three providers. Google draws the line at messages sent for legal reasons or in response to an explicit action by the user, giving password resets, purchase receipts and one-time passcodes as examples; Yahoo states the requirement covers promotional and marketing messages and does not apply to transactional ones. Beyond the exemption, adding an unsubscribe control to transactional mail is an error: a password reset is not a subscription, and honoring an opt-out from it could lock the recipient out of their account. Use List-Help instead, pointing at support.
Google requires unsubscribe requests to be processed and honored within 48 hours. Yahoo requires them to be honored within two days and states explicitly that an unsubscribe not honored in two days does not meet the requirement. Microsoft does not publish a processing deadline. Recording the request is not the same as honoring it: a suppression list applied at campaign build time rather than at send time can easily exceed both windows.
No. Google's bulk sender guidelines cover senders of more than 5,000 messages per day to personal Gmail accounts. Mail to Google Workspace accounts is not counted toward that threshold and is governed separately. This matters for B2B programs, where a large share of the list may be corporate Workspace addresses: the sender can be under Google's threshold while their own total volume looks well over it.
Enforcement has moved from filtering to rejection. Microsoft began rejecting mail that fails its authentication requirements at the SMTP level in May 2025, returning 550 5.7.515, rather than routing it to the junk folder as originally announced. Google escalated during November 2025 from temporary failures to permanent rejection for traffic that does not meet its requirements. A non-compliant message is increasingly not a message in the spam folder but a message that was never delivered.
Because security gateways and link scanners follow GET links to check them for malware and phishing, before the recipient ever sees the message. A GET-based unsubscribe URL is an ordinary link to that infrastructure, so it gets fetched, and fetching it performs the unsubscribe. Requiring a POST with a specific body means an automated fetch that follows links cannot trigger the action behind the URL.
If the unsubscribe endpoint acts on a GET request, yes, and it happens routinely. Security vendors do make an effort to recognize unsubscribe links and leave them alone, and they get it wrong regularly. That is precisely the failure RFC 8058 was written to prevent. An endpoint that only acts on a POST carrying List-Unsubscribe=One-Click cannot be triggered by link scanning.
Yes, and unlike unsubscribes there is no standard preventing it. Double opt-in confirmation links are almost always plain GET URLs, so the same scanning infrastructure that follows an unsubscribe link follows the confirmation link and records a subscription the recipient never confirmed. The result is a consent record with a timestamp on it that reflects a security scanner rather than a person.
Make the confirmation link render a page rather than perform the confirmation. The page should require a deliberate action before the opt-in is recorded: a checkbox and a submit button, a CAPTCHA and a confirm button, or any equivalent interaction an automated fetch cannot complete. As a rule, a GET request should render the confirmation page and only a subsequent POST from that page should record consent. It is the same principle RFC 8058 applies to unsubscribes, applied to the opposite end of the subscription lifecycle.
No. Consent under the GDPR requires a freely given, specific, informed and unambiguous indication of the recipient's wishes, given by a clear affirmative action, and the burden of demonstrating it sits with the controller. A confirmation generated by a security scanner is none of those things. The record will look valid in a database and will not survive being challenged, which is why the confirmation step needs to be one an automated system cannot complete.
No. Microsoft's requirements for high-volume senders, announced in April 2025 and enforced from 5 May 2025, mandate SPF, DKIM and DMARC along with a functional and clearly visible way to opt out. One-click unsubscribe under RFC 8058 is supported and recommended but not mandated, so failing RFC 8058 alone does not make a sender non-compliant with Microsoft. Google and Yahoo are stricter on this point, and implementing RFC 8058 is the sensible default regardless.
The provider requirements on this page are quoted from each provider's own documentation rather than from secondary commentary, because the differences between them are exactly what secondary commentary flattens. All checked September 2026; all three providers revise these pages.
List-Unsubscribe-Post header, and the POST mechanism.List-Unsubscribe and the other list headers long before one-click existed.This page covers the opt-out end of the subscription lifecycle. The opt-in end has the same problem and none of the protection.
Omnivery applies RFC 8058 one-click unsubscribe to marketing messages and List-Help to transactional ones, whether or not the system above it emits them. Correct categorization is not left to the sending application to get right.