A Brief History of an Underused Header

The List-Unsubscribe header was defined in RFC 2369 way back in 1998. Its original purpose was simple: give recipients a machine-readable way to opt out of a mailing list. The value was a URL or mailto link the recipient's mail client could expose as a one-click unsubscribe button.

For two decades, the header was widely ignored. Marketers added it because the spec said to, but receivers didn't enforce it and most mail clients didn't expose the unsubscribe button prominently. The actual unsubscribe link was usually buried in the email's HTML body, where every spammer also had a fake "click here to unsubscribe" link that did nothing or marked your address as confirmed-active.

That changed in 2018 with RFC 8058, which added the List-Unsubscribe-Post header alongside the original List-Unsubscribe. The new combination defined a standard one-click HTTP POST flow that mail providers could call automatically when a user clicked "unsubscribe" — no need to load the sender's website, no risk of confirming the address as live, just an immediate clean opt-out.

2024: Enforcement Becomes Universal

In early 2024, Gmail and Yahoo simultaneously announced that bulk senders must include RFC 8058-compliant List-Unsubscribe and List-Unsubscribe-Post headers, or their mail would be rejected outright. Microsoft followed shortly after with similar requirements for Outlook.com.

The threshold for "bulk sender" varies by receiver but is generally pegged at 5,000 messages per day. Above that volume, no compliant List-Unsubscribe headers means your mail gets bounced or sent straight to spam at the major consumer mail providers. This created an immediate, hard incentive for every legitimate ESP — Mailchimp, SendGrid, Constant Contact, every transactional mail provider — to ensure their customers' mail is RFC 8058 compliant.

The result, two years later, is that the presence of a properly-formed List-Unsubscribe + List-Unsubscribe-Post header pair is now near-universal among legitimate bulk senders. Conversely, fly-by-night spam operations either skip these headers entirely or include malformed versions — they don't have the infrastructure to honor unsubscribes, and they don't want to invest in deliverability anyway because their delivery model relies on volume rather than reputation.

Why This Makes a Great Spam Signal

The asymmetry is what makes List-Unsubscribe powerful as a classification signal. For a legitimate bulk sender, including these headers is mandatory and their ESP handles it automatically — zero marginal cost. For a spammer, including the headers correctly requires actually running an unsubscribe endpoint that responds to one-click opt-outs (or their domain reputation dies quickly when receivers test the link). That's a non-trivial cost, and most spammers don't bother.

So the rule "presence of valid List-Unsubscribe = probably legitimate bulk mail" has very high precision. False positives are rare, and they tend to be benign — a small newsletter operator who set up unsubscribe properly is exactly the kind of "promotional" mail you want classified as such.

Spam Killer's promotional classifier checks for the header (the simpler RFC 2369 form, since RFC 8058 compliance is a strict superset). Combined with SPF, DKIM, and MX validation, it's enough to route the message to [PROMOTION] with confidence.

The Bulk Header Family

List-Unsubscribe is the most important, but it's not the only bulk-mail header. Spam Killer's promotional classifier looks for several:

List-Unsubscribe — opt-out link or mailto. The single strongest indicator.

List-Id — uniquely identifies the mailing list. Required by mailing list software like Mailman and used voluntarily by most ESPs.

Precedence: bulk — older convention but still in active use. Mailman, Sympa, and many in-house bulk mailers add this automatically.

Any one of these counts as a promotional indicator with default min_indicators: 1. Multiple presence is common in legitimate mail and provides extra confidence.

Tuning the Check

You can disable the List-Unsubscribe check independently if your environment has unusual bulk mail patterns:

classification:
  promotional:
    check_list_unsubscribe: true   # default
    check_precedence_bulk: true    # default
    check_list_id: true            # default
    min_indicators: 1              # require at least one

For a tighter promotional classifier that requires the explicit RFC 2369/8058 signal:

classification:
  promotional:
    check_list_unsubscribe: true
    check_precedence_bulk: false
    check_list_id: false
    check_marketing_sender: false
    check_marketing_mailer: false
    min_indicators: 1

This effectively says: "only classify as promotional if a List-Unsubscribe header is present." High precision, will miss some legitimate but less-rigorously-configured bulk mail.

Why Senders Should Care Too

If you send any volume of email (not just receive it), the List-Unsubscribe story matters from the other side too. Without compliant headers, your mail will increasingly fail to land in inboxes at major receivers — Gmail, Yahoo, Outlook all enforce this now, and corporate spam filters are increasingly checking for it.

If you use a major ESP, this is handled for you. If you send mail directly from your own infrastructure (transactional mail from a backend service, internal tooling that emails users), make sure your sending code includes proper List-Unsubscribe headers for any mail that goes to more than a handful of recipients. The implementation is straightforward and the deliverability win is significant.