What is the List-Unsubscribe header in newsletters and marketing emails?

When you open a newsletter, you might notice an unsubscribe button right next to the sender address. This button is powered by the List-Unsubscribe header, which tells mail providers how recipients can unsubscribe from a mailing list.

At Lettermint, we automatically add the correct List-Unsubscribe headers to all your broadcast emails. In this article, we explain what the List-Unsubscribe header is, how it works, and what requirements you need to meet.

What is the List-Unsubscribe header

The List-Unsubscribe header is an email header that tells mail providers how recipients can unsubscribe. The main goal isn't necessarily to show a visible button, but to protect both recipients and senders.

When recipients can't easily unsubscribe, they use the spam button. Every spam complaint damages your sender reputation. A poor reputation means your emails land in spam or get rejected entirely. The List-Unsubscribe header provides an alternative: recipients can unsubscribe without marking you as spam.

Mail providers use this header in different ways. Gmail and Yahoo often show an unsubscribe button next to the sender address, but only for senders with a good reputation. Other providers like Outlook process the header in the background without a visible button. Either way, the result is the same: a smooth unsubscribe process that protects your reputation.

There are two versions of this header:

1. List-Unsubscribe: contains a URL or email address for unsubscribes
2. List-Unsubscribe-Post: indicates that one-click unsubscribe is supported

Both headers work together. The first header has existed since 1998 (RFC 2369). The second was added in 2017 with RFC 8058 to prevent abuse.

List-Unsubscribe

The List-Unsubscribe header has existed since 1998 and is described in RFC 2369. This header contains a URL and/or mailto address that allows recipients to unsubscribe:

      List-Unsubscribe: <https://example.com/unsubscribe?id=123>, <mailto:unsubscribe@example.com>

    

You have three options:

• URL only
• Mailto address only
• Both (recommended)

Not every mail provider supports both methods in their own webmail or app:

List-Unsubscribe-Post

Since 2017, there's an additional header: List-Unsubscribe-Post, described in RFC 8058. This header enables one-click unsubscribe directly from the email client. When you click "Unsubscribe" in Gmail's interface for example, Gmail sends a POST request to the URL. This way, the recipient doesn't need to visit a webpage or confirm anything. One click and done.

The value is always the same:

      List-Unsubscribe-Post: List-Unsubscribe=One-Click

    

In practice, you use both headers together:

      List-Unsubscribe: <https://example.com/unsubscribe?id=123>, <mailto:unsubscribe@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

    

List-Unsubscribe at Lettermint

The List-Unsubscribe header only applies to our Broadcast route. For Transactional emails like order confirmations and password resets, an unsubscribe option isn't needed and often even unwanted.

For broadcast emails sent through Lettermint, you don't need to configure the List-Unsubscribe header yourself. We handle it automatically, saving you extra work while ensuring your emails comply with guidelines from mail providers like Gmail, Yahoo, and Outlook.

What does Lettermint handle automatically?

• List-Unsubscribe header: We add a URL
• List-Unsubscribe-Post header: We support one-click unsubscribe per RFC 8058
• Unsubscribe link in the email: Every broadcast email includes a visible unsubscribe link at the bottom

When a recipient unsubscribes via the header or the link, we process it immediately. The email address is added to your suppressions list. This prevents new emails from being sent to this address via the broadcast route.

Syncing unsubscribes with your own system

Want to process unsubscribes in your own database as well? You can do that via:

• API: Retrieve suppressions via our API
• Webhooks: Receive a notification when someone unsubscribes

Using your own unsubscribe system?

In exceptional cases, we can disable the automatic unsubscribe link. This is only possible if you have your own fully functional unsubscribe system. You must then ensure you include a visible unsubscribe link in your emails and send the correct List-Unsubscribe and List-Unsubscribe-Post headers yourself. Contact our support team.

Conclusion

The List-Unsubscribe header is an important part of email marketing. It gives recipients an easy way to unsubscribe, reducing spam complaints and improving your sender reputation. Major mail providers like Gmail and Yahoo now require this header for bulk senders.

At Lettermint, you don't need to worry about this. We automatically add the correct headers to all your Broadcast emails and manage unsubscribes for you. This way, you always comply with the guidelines.