A tangent about the List-Unsubscribe header

On a technical level, the type of mailbox-side polite unsubscribe request we mentioned in our previous post is implemented using the List-Unsubscribe email header.

Messages containing this header will offer handy unsubscribe options, and Gmail’s user interface will often intentionally nudge recipients in the direction of politely unsubscribing this way instead of actually filing a spam complaint – as a way to encourage senders to implement it.

When present, this header is basically a hyperlink, but multiple implementations are possible.

It can be implemented as an https:// link, in which case your inbox software will direct you to the specified web page when you click unsubscribe. From there you usually have to fill out a form to finish unsubscribing.

Or it can be implemented as a mailto:// link, in which case your inbox software will send an email on your behalf to the specified email address.

List-Unsubscribe with a mailto link

If a mailto:// link is used, unsubscribe requests are sort of inherently handled asynchronously, so they will often not processed immediately.¹ (Of course, there’s never any guarantee that an unsubscribe request will be processed immediately. But with mailto:// links there is kind of a guarantee that they won’t be.)

For a long time, a mailto:// link has been more common and encouraged, as a lower-tech option that was more universally applicable and easier for inbox software to fully automate.

This could be as simple as mailto:list-manager@host.com?subject=unsubscribe%20list – messages received by list-manager@host.com whose subject line was "unsubscribe list" could then be reliably processed as an unsubscribe request, looking up whoever sent the message and unsubscribing that person automatically or manually.

Over time, more complex implementations evolved, and it’s now more common to see it implemented like mailto:list-manager@host.com?subject=unsubscribe:dDotJRMV393VJf-AicmNwdF90byICJoZWxsb0B0aGlyZGJlYXJzb2x1d or mailto:dDoJRMV393VJf-B0aGlyZGJlYXJzb2x1d@host.com?subject=Unsubscribe where details about the recipient to unsubscribe and the specific message they are reacting to are encoded in the email address, subject line, or message body.

Using both options

The header is allowed to have multiple values separated by a comma, so it‘s possible to provide both a mailto:// option and an https:// option simultaneously. Inbox software can then choose which of those options they want to use when you use their unsubscribe prompts.

This is helpful because not all inbox software supports both methods. For example, Outlook and Yahoo Mail both only support the mailto:// option. Litmus has a handy chart of who supports what, if you‘re curious.

What‘s a one-click unsubscribe?

More recently, a second email header was introduced to make the https:// option more useful.

This header, List-Unsubscribe-Post, tells inbox software “you can make an HTTP POST request directly to my List-Unsubscribe URL and I’ll process an unsubscribe request — no user interaction is needed, so you don‘t need to take the end user to a landing page first.

This is also referred to as a “One-Click Unsubscribe“ option (which is a little confusing, because the mailto:// method was always a one-click unsubscribe) — and it‘s also now required by Google‘s new sender guidelines, but only sometimes:

• Only bulk senders (who have sent at least 5,000 messages in a single day to Gmail recipients at least once) are required to implement RFC 8058‘s One-Click Unsubscribe with a List-Unsubscribe-Post header and an https:// List-Unsubscribe option. If you’re not a bulk sender according to Gmail, you don‘t need to implement this.
• For bulk senders, only bulk mail that isn‘t triggered by the end user needs to implement this. So you need List-Unsubscribe-Post in your marketing and promotional messages, advocacy asks, donation requests, newsletter updates, and so on. But you don‘t need it in your donation receipts, after-action messages, login confirmations, and other transactional mail.
• None of this is actually required until June 1, 2024, assuming you‘ve already been including unsubscribe links in all your message footers.

Gmail still continues to support the mailto:// option for List-Unsubscribe headers in parallel, but that does not meet their one-click unsubscribe requirement for bulk senders‘ bulk mail.

All of that said, you almost certainly don‘t need to worry about any of this: your bulk mailing toolset handles the implementation details here, and it has probably already been compliant for a while.²

Who gets to have unsubscribe buttons?

Even if your message includes a List-Unsubscribe header, Gmail doesn‘t always display those handy unsubscribe buttons.

Google doesn‘t publish any sort of official requirements, but basically, Google will only start to display Unsubscribe buttons if they trust you.

(Remember, those unsubscribe buttons are a favor that Gmail is doing for you — every known polite unsubscriber is one less anonymous spam complaint.)

Essentially, that means you need to have sent enough mail over a long enough time — with healthy enough open / click / complaint ratios and a clear pattern of respecting unsubscribes — to establish a good reputation as a trustworthy sender.

Based on what I see in my own inbox, I suspect you also need strict domain alignment (SPF and/or DKIM) but I‘m not seeing anything on the web to confirm this so it may be a coincidence.