Unsubscribe with one click: the List-Unsubscribe header

In Gmail, Yahoo and Apple Mail you'll see an Unsubscribe button at the top of many newsletters. That button doesn't come from the text of the email, but from a header: List-Unsubscribe. If you send a newsletter yourself, that header is required these days. In this article you'll read what it does and how to check that it's set up correctly.

Two headers

Headers are the lines above the actual email that you normally don't see. For unsubscribing there are two:

List-Unsubscribe: <https://nieuwsbrief.jouwdomein.nl/afmelden?id=8f3a2c>, <mailto:afmelden@jouwdomein.nl?subject=afmelden>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

• List-Unsubscribe provides a web address and optionally an email address that the recipient can use to unsubscribe.
• List-Unsubscribe-Post indicates that one-click unsubscribing works (RFC 8058). When the recipient clicks Unsubscribe, their mail program sends a request to the web address and they're unsubscribed immediately. No extra page, no logging in, no "are you sure?".

When is it required?

Gmail and Yahoo require one-click unsubscribing in marketing and subscription emails from senders who send a lot of mail (from roughly 5,000 per day to Gmail). An unsubscribe request must be processed within 2 days. Even if you're smaller, the button helps: people who can easily unsubscribe are less likely to click "This is spam". Read more about these requirements in The requirements from Gmail, Yahoo and Microsoft for those sending a lot of mail.

How to set it up

• Via a newsletter service: usually you don't need to do anything. A good service adds both headers itself and processes the unsubscribes. Do check it with a test email.
• With a plugin or your own software: check the settings to see if the software supports List-Unsubscribe and one-click unsubscribing. If you're building it yourself, follow the rules from RFC 8058: the web address is https, contains a unique code per recipient, doesn't redirect to another address, and only unsubscribes on a POST request. A regular visit to the link (GET) should not unsubscribe, since virus scanners automatically open links in email. The two headers must fall under the DKIM signature.

It's best not to send a newsletter to a large number of people through your hosting package. There's a daily sending limit for that. Read Am I allowed to send a mailing via my hosting package at WebOké?

Checking the headers

1. Send your newsletter to your own Gmail address.
2. Open the email, click the three dots on the right and choose Show original.
3. Look for List-Unsubscribe. Is there an https address in it, and below that List-Unsubscribe-Post: List-Unsubscribe=One-Click?
4. Find the DKIM-Signature line. After h= are the headers that are signed. List-Unsubscribe and List-Unsubscribe-Post should be among them.

Consent

Unsubscribing is the flip side of consent. In the Netherlands, you're only allowed to send advertising by email to people who gave prior consent for it, with an exception for existing customers regarding similar products. A confirmed sign-up (double opt-in) gives you proof. The Authority for Consumers & Markets explains the rules on its page about spam.