A Russian translation of this article is also available here.

If you use Gmail or frequently send mailing list emails you probably know that Gmail has an inline automatic unsubscribe button. If you hit this button then Gmail magically unsubscribes you from that mailing list.

I've spoken about this before on Twitter but although it seems counterintuative, allowing people to easily unsubscribe is the best way to maintain a healthy mailing list.

So in this post I want to disect exactly how the Gmail unsubscribe button works, and if you're a mailing-list owner, how to make sure it always shows up for your emails.

There are a few ways to provide unsubscribe links, when used properly they compliment each other by letting every type of client unsubscribe easily. Starting with the most obvious (and often infuriating)...

Unsubscribe links in the email content

The most common method you'll see everywhere is to provide an unsubscribe link directly within the email content, usually hidden away at the bottom of the email.

Gmail seems to handle some of these links, specifically when the link contains the word "Unsubscribe".  Clicking the Gmail unsubscribe link using the case above shows the following prompt:

But I found if the link contains unusual wording or formatting then Gmail doesn't find it correctly. A likely explanation is they're using a set of regular expressions to parse the email content - quite a brittle approach.

You're also still required to actually visit the link in most cases we tried, which limits it's usefulness somewhat. It's barely easier than finding and clicking the small unsubscribe link in the email.

(It's probably obvious by now - I do have some strong feelings about tiny unsubscribe links skulking right at the bottom of email footers, but that's a topic for another day.)

List-Unsubscribe

A more predictable approach is to use the List-Unsubscribe header (RFC 2369). Attached to the metadata of an email, the header is designed to provide the method to unsubscribe in a machine readable format.

The header can have a number of different formats, but the most common is to provide a mailto and URL like this:

List-Unsubscribe: 
  <mailto:test@example.com>, 
  <https://example.com/unsubscribe?uid=0000>

If you're using a mailing list provider such as Sendgrid or Mailchimp then they should already insert these headers into the email for you, so you shouldn't need to do anything extra with this.

It appears from testing that Gmail will favour the mailto method, sending an email to the address provided. You can verify this by checking your sent email folder, which will contain items like this;

This is by far the simplest approach, sending an email is what Gmail is good at after all. However, I'm somewhat sceptical of the effectiveness of this method, or maybe it just feels too easy.

As far as I can tell Gmail treats URLs in the List-Unsubscribe header identically to unsubscrbe links in the content of emails, which makes sense as they should be the same URL in most cases.

List-Unsubscribe-Post

One problem with List-Unsubscribe or content links is they could take you to a page that requires extra steps, such as logging in or entering your email address. Despite how you feel about this (I dislike it a lot), it makes things very difficult to automate an unsubscribe like Gmail is trying to do.

However, there's a newer unsubscribe standard header called List-Unsubscribe-Post that designates single-request unsubscribe functionality (RFC 8058). If an email contains this header then the unsubscribe link can simply be activated by sending a single POST request to the URL.

Unfortunately it's much less common than List-Unsubscribe to see in the wild. I could actually only find one example of this in my inbox (shout out to Substack, nice work folks).

As far as I can tell Gmail does nothing with this header, but it's a nice-to-have on your mailing list if you want to cover all the bases.

That about wraps it up for our unsubscribe options. If you're running a mailing list and want to make it easy for your recipients to unsubscribe (you should), then implementing these things will be a great addition and help you maintain a healthy list in the long run:

1. Include an unsubscribe link in the content of the email in a clear, legible way, using simple language. Using the word "Unsubscribe" in the link is probably a good idea.
2. Include a List-Unsubscribe header with a mailto and URL. If you're using a mail service, make sure they are including this automatically. You can check the source of an email to do this - here's a post on how to do that.
3. Where possible make your unsubscribe link work with a single click!

PS.

One extra thing I found out was that Gmail doesn't seem to show the unsubscribe button until you've received a few emails from a particular sender. This makes sense I suppose, but seemed to behave quite unpredicably.

Also for some emails it just straight up doesn't show the button and I couldn't find an explanation. Perhaps there's some extra step going on behind the scenes or something I'm missing.

If you know the answer to either of these unknowns then let me know on the HN thread and I'll credit you here :)

PPS.

If you enjoyed this post then check out my Twitter. I spend my free time tweeting about my hatred for horrible unsubscribe practices and crappy mailing list emails. See you there!