List-Unsubscribe and one-click unsubscribe headers, explained

The headers are what put an Unsubscribe link next to the sender's name in Gmail and other mail apps. Google shows it only for messages that pass its own eligibility checks, so adding the headers doesn't guarantee the button appears. A visible link in the email body is still expected as well: it can go to a preferences page rather than unsubscribing straight away.

Each URL sits in angle brackets. With several, separate them with commas; the mail app uses the leftmost one it supports. A message carries one List-Unsubscribe header, so the two lines above are alternatives, not a pair.

When the reader clicks Unsubscribe, their mail provider sends this request to your URL. There are no cookies and no login: everything you need to identify the reader and the list has to be in the URL.

RFC 8058 also requires a valid DKIM signature whose h= tag lists both headers, so the receiver knows they came from the signing domain and weren't added on the way:

Google says it doesn't automatically reject or spam-folder mail just for missing one-click unsubscribe, but senders who don't meet the requirements aren't eligible for its delivery mitigation, and readers who can't unsubscribe easily are more likely to press Report spam. Microsoft's rules for Outlook.com recommend a working unsubscribe link. The full set of authentication and volume rules is in Google, Yahoo and Microsoft sender requirements.

The law sets its own floor. In the US, the FTC's CAN-SPAM guide says commercial email needs an opt-out that keeps working for at least 30 days after sending and is honoured within 10 business days, and that transactional or relationship messages are exempt from most of the Act. Other countries have their own rules.

No. Google's FAQ says one-click unsubscribe is required only for marketing and promotional messages, and gives password resets, reservation confirmations and form submission confirmations as examples of transactional mail that's excluded. The same FAQ adds that "message recipients, not Google, determine the nature of the messages they receive", so what counts is how your readers see a message, not what you call it.

Adding the headers to a password reset isn't harmless. A reader who clicks Unsubscribe on it usually lands on your suppression list, and then their next password reset doesn't arrive. Keep unsubscribe for mail people can do without, and send account and security mail without it. Don't mix the two in one message either: Google's guidelines say not to put promotions in receipts. Send them as separate emails.

Groundmail adds the one-click headers for you, based on each email's category, and runs the unsubscribe endpoint. Each category also goes out on its own servers and IPs, so a product announcement never shares IPs with your sign-in codes.

When managed unsubscribe is on, Groundmail adds both headers with a signed HTTPS link bound to the first to address, and replaces {{unsubscribe_url}} in your subject, HTML and text with a link to a confirmation page. The one-click URL only unsubscribes on a POST; opening it in a browser shows the confirmation page, so link scanners can't unsubscribe anyone by accident.