List-Unsubscribe header: what it is and why it matters

List-Unsubscribe is an email header that tells the mail client how a recipient can opt out of a mailing list. When it is present, Gmail, Yahoo Mail, Outlook, and other clients display an "Unsubscribe" button next to the sender address, so the recipient never has to hunt for a link in the message body.

What the header looks like

The header goes in the message envelope, not the HTML body. It has two forms:

Both values can appear together, separated by a comma. The mailto variant sends an email to the specified address; the HTTP variant calls the URL. The mail client picks whichever method it prefers.

List-Unsubscribe-Post and one-click unsubscribe

RFC 8058, published in 2017, defines a true one-click mechanism. It requires a second header alongside the first:

With both headers in place, the mail client can remove the recipient by sending a single POST request to the URL, no website visit needed. The user clicks once and that is it.

Gmail and Yahoo requirements since 2024

In February 2024, Google and Yahoo tightened their rules for bulk senders, defined as anyone sending more than 5,000 messages per day to their domains. Three conditions are now required:

• Every marketing message must include a List-Unsubscribe header with an HTTP URL.
• One-click unsubscribe via List-Unsubscribe-Post must be supported.
• Unsubscribe requests must be honored within two days.

Senders who ignore these requirements face delivery restrictions. Gmail can start rejecting messages or routing them to spam.

Why the header benefits the sender

It seems counterintuitive to make opting out easier. The logic is simple though: if a subscriber cannot find the unsubscribe link, they hit "Spam" instead. A spam complaint damages domain reputation directly. An unsubscribe through List-Unsubscribe does not generate a complaint at all.

Mailbox providers also read the header as a signal of responsible sending. Its absence in 2025 is treated as a red flag, not a neutral omission.

Setting it up through an ESP

Most email service providers, including Mailchimp, SendGrid, and Brevo, add the header automatically for marketing sends. If you send through your own SMTP server, you must add it manually.

The minimum setup: include an HTTPS URL in List-Unsubscribe and add the List-Unsubscribe-Post header. Your server needs an endpoint that accepts a POST request and removes the address from your list without any further interaction required.

Common mistakes

• Mailto only, no HTTP URL. Gmail and Yahoo require the HTTP variant. A mailto address alone does not satisfy the one-click requirement.
• Missing List-Unsubscribe-Post. Without this second header the one-click mechanism does not work. Some clients will show no button at all.
• The URL leads to a confirmation page. One-click means one click. If the POST endpoint requires additional user action before removing the address, it violates RFC 8058.
• Requests are not processed. The button exists but the backend never removes the address. The recipient keeps receiving mail and files a spam complaint.

Transactional vs marketing messages

List-Unsubscribe is for marketing and newsletter sends. Transactional messages, such as order confirmations, password resets, and login alerts, should not include it. Those messages are triggered by user actions, so opting out of them does not make sense.