The List-Unsubscribe Header and One-Click Unsubscribe

The List-Unsubscribe header tells mail apps how to unsubscribe someone from your list. Gmail, Yahoo, Apple Mail and Outlook use it to show an Unsubscribe button next to the sender’s name. With the List-Unsubscribe-Post header added, that button unsubscribes the person in one click, without opening a web page. Since 2024, Gmail and Yahoo require one-click unsubscribe on bulk marketing mail.

What the headers look like

List-Unsubscribe: <https://example.com/unsubscribe/8f3a2c>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
  • List-Unsubscribe holds one or more unsubscribe addresses in angle brackets: an HTTPS URL, a mailto: address, or both. It has existed since RFC 2369 in 1998.
  • List-Unsubscribe-Post says the HTTPS URL accepts a one-click POST request. It is defined in RFC 8058 and always has the exact value List-Unsubscribe=One-Click.

How one-click unsubscribe works

When someone clicks Unsubscribe in their mail app, the mailbox provider sends an HTTP POST to your URL with the body List-Unsubscribe=One-Click. Your server unsubscribes that person and returns a success status. The subscriber never sees a page, confirms nothing and logs into nothing.

For that to be safe, a few rules apply:

  • The URL must be HTTPS and identify the subscriber on its own, usually with a unique token. The POST carries no cookies or login.
  • The request must not require a confirmation step. One click means one click.
  • Both headers must be covered by your DKIM signature, so no one can tamper with them in transit.
  • The URL must accept POST. A GET to the same URL can still show a confirmation page for people who click a link in the email body.

What Gmail and Yahoo require

Since 2024, Gmail and Yahoo require senders of bulk email (Gmail’s line is around 5,000 messages a day to its users) to:

  • support one-click unsubscribe with List-Unsubscribe and List-Unsubscribe-Post on marketing and subscribed messages
  • process unsubscribe requests within two days
  • include a clearly visible unsubscribe link in the message body as well
  • authenticate with SPF, DKIM and DMARC, and keep spam complaints under 0.3%

Transactional email, like receipts and password resets, doesn’t need an unsubscribe header. Microsoft applies similar authentication rules to large senders to Outlook.com addresses.

Common mistakes

  • A mailto: only. It still shows the Unsubscribe button in some apps, but it isn’t one-click. Add an HTTPS URL and List-Unsubscribe-Post.
  • A URL that needs a login or a confirmation click. Mailbox providers treat that as not one-click.
  • Headers added after signing. If your sending service adds the headers after DKIM signing, they aren’t covered. Check the h= list in your DKIM-Signature.
  • Unsubscribes that don’t stick. If a POST unsubscribes someone but your next import or sync re-subscribes them, complaints follow.

How to check your headers

Send a test to a Gmail address, open it and choose Show original. Look for both headers. Or paste the original message into our email header analyzer, which flags a missing List-Unsubscribe on bulk mail and a missing List-Unsubscribe-Post. The deliverability test includes the same check in its score.

How Broadcast handles it

Broadcast adds both headers by default on every email server you connect, with a unique, signed unsubscribe URL for each subscriber, so one-click unsubscribe works without any setup. You can turn the headers off for a server that only sends transactional email, and transactional emails sent through the API don’t carry them unless you ask. The unsubscribe settings documentation has the details.

Frequently asked questions

What is the List-Unsubscribe header?

An email header that gives mail apps a way to unsubscribe the recipient, through a URL, an email address or both. Mail apps use it to show a built-in Unsubscribe button.

What is one-click unsubscribe?

Unsubscribing in a single click from the mail app, with no web page or confirmation. It needs the List-Unsubscribe-Post: List-Unsubscribe=One-Click header and an HTTPS URL that accepts POST, as defined in RFC 8058.

Is one-click unsubscribe required?

For bulk marketing email to Gmail and Yahoo users, yes, since 2024. It is good practice for any list.

You still need one, but it doesn’t replace the headers. Gmail and Yahoo require both the header-based one-click unsubscribe and a visible link in the message.