One-Click Unsubscribe: How List-Unsubscribe Headers Work

Short answer: One-click unsubscribe lets recipients leave a mailing list with a single click on an “Unsubscribe” button shown by their mail app, without visiting a website or logging in. It works through two e-mail headers defined in RFC 8058: List-Unsubscribe with an HTTPS URL, and List-Unsubscribe-Post: List-Unsubscribe=One-Click. Gmail and Yahoo require it for bulk marketing mail, together with a visible unsubscribe link in the message and processing of requests within two days.

Why one-click unsubscribe matters

When unsubscribing is hard, recipients use the tool that is always one click away: the “Report spam” button. For them the effect is the same, the mail stops. For you it is very different. A spam report damages your sender reputation, while an unsubscribe simply removes a person who no longer wants your mail.

Mailbox providers know this, which is why they show their own unsubscribe button next to the sender name when a message carries the right headers. Gmail and Yahoo made one-click unsubscribe a requirement for bulk senders in 2024 for marketing and subscribed messages. It lowers complaint rates, respects recipients and makes lists healthier, because people who are not interested leave instead of silently ignoring you.

Some senders worry that a visible unsubscribe button will shrink their list. It does, but mostly by removing people who were not reading anyway. Those contacts drag down engagement, which filters also watch, so a slightly smaller list of interested readers usually performs better than a large list full of silent ones.

There is also a legal side. Many privacy and marketing laws require an easy way to opt out of commercial messages. One-click headers are not a legal requirement in themselves, but they support the principle that leaving should be as easy as joining.

The two headers

List-Unsubscribe has existed for a long time (RFC 2369). It contains one or more URIs in angle brackets, separated by commas:

List-Unsubscribe: <https://example.com/unsub?id=abc123>, <mailto:[email protected]?subject=unsubscribe>

On its own, an HTTPS link in this header could be opened by a mail client, but that is risky: security scanners and link-preview systems also open links, and a simple GET request that unsubscribes someone could remove people who never asked.

List-Unsubscribe-Post, defined in RFC 8058, solves that. When present with the exact value List-Unsubscribe=One-Click, it tells the mail provider to send an HTTP POST request to the HTTPS URL with the body List-Unsubscribe=One-Click. Scanners do not send POST requests of this kind, so accidental unsubscribes are avoided, and the provider can unsubscribe the recipient in the background without opening a page.

Technical requirements that are easy to miss

• The HTTPS URL must handle POST and unsubscribe the recipient without further confirmation, login or preference page. A page asking “are you sure?” does not meet the one-click standard for the POST request.
• The URL must identify the recipient and list, usually with an opaque token. Do not put the plain e-mail address in the URL, which leaks personal data into logs.
• Both headers must be covered by the DKIM signature. RFC 8058 requires that the message carry a valid DKIM signature that covers the List-Unsubscribe and List-Unsubscribe-Post headers, so receivers know they were not added by someone else.
• The endpoint must respond successfully and must not redirect the POST to another location that fails.
• A mailto option is optional but useful for clients that do not support HTTPS unsubscribe. If you include it, someone must process mail sent to that address.

Which messages need it

A useful test: if the recipient could reasonably say “I don’t want these any more” without losing access to a service they use, the message needs an unsubscribe option. Be honest about classification. Promotional content inserted into “transactional” mail makes it marketing mail.

How to set it up

If you use an e-mail marketing platform, it very likely adds both headers already. Check the platform’s documentation and confirm by viewing the headers of a campaign sent to your own Gmail address. Make sure your custom domain DKIM is active, because the headers must be covered by a valid signature, ideally one aligned with your domain.

If you send from your own system, such as a web application or a CRM with custom sending:

1. Create an unsubscribe endpoint on HTTPS that accepts POST requests with the body List-Unsubscribe=One-Click, identifies the recipient from a token in the URL, and records the opt-out immediately.
2. Let the same URL respond to GET with a simple confirmation page, for recipients who click it manually, without auto-unsubscribing on GET.
3. Add both headers to each marketing message, with a per-recipient token.
4. Make sure your DKIM signing includes those headers in its signed header list (h=).
5. Keep a visible unsubscribe link in the message body or footer as well.

Log every unsubscribe with a timestamp and the source (header, footer link, reply). The log helps when someone later claims they unsubscribed and kept receiving mail, and it shows whether a particular campaign triggered unusually many opt-outs. A spike in unsubscribes after one message is useful feedback: the content, the audience or the frequency did not match what those people signed up for.

If an agency or developer builds the endpoint for you, ask for a short test plan covering POST, GET, invalid tokens and repeated requests. Repeated requests should simply succeed again, not produce errors, because providers may retry.

How to test it

1. Send a campaign to a personal Gmail account.
2. Check whether Gmail shows an “Unsubscribe” option next to the sender name. Gmail may not display it for every message or sender, especially at low volumes, so its absence is not always an error.
3. Use “Show original” to confirm both headers are present and that DKIM passes.
4. Check the DKIM-Signature header’s h= list for List-Unsubscribe and List-Unsubscribe-Post.
5. Test the endpoint directly with a POST request using a test token, and confirm the address is removed from the list.
6. Send another campaign and confirm the test address no longer receives it.

Processing unsubscribes on time

Google and Yahoo expect unsubscribe requests to be honoured within two days. That sounds easy, but lists often live in several systems: the newsletter tool, the CRM, the e-commerce platform and spreadsheets used for one-off campaigns. An unsubscribe recorded in one place and ignored in another leads to exactly the complaint you wanted to avoid.

• Choose one system as the master list for marketing consent, and sync opt-outs to all others.
• Apply suppression lists to every import, so an old spreadsheet cannot re-add people who left.
• Make sure that unsubscribing from one list type does not require separate action for others the person clearly wants to leave; a preference centre is fine as an extra, not as the only option.

Common mistakes

• Unsubscribe link that requires login. This fails one-click and frustrates recipients.
• Header present, but DKIM does not cover it, or DKIM fails, so providers ignore the header.
• Endpoint returns an error or redirect for POST requests.
• Unsubscribes that “take up to 10 business days”. Too slow under the current requirements.
• Hiding the footer link in tiny grey text. Recipients who cannot find it will press “Report spam”.
• Tokens that expire. An unsubscribe link in a message from six months ago must still work; people often unsubscribe from old mail.

The authentication behind it

One-click unsubscribe relies on DKIM, and the bulk sender rules that require it also require SPF, DKIM and DMARC. Site AI Audit checks those records, SPF with its lookup limit, DKIM, DMARC and MX, and explains each finding in plain words, so you can confirm the foundation is in place. A free check shows the current state; paid plans keep watching and alert you when a record breaks.

Related reading

• Gmail and Yahoo Bulk Sender Requirements: A Practical Guide
• Google Postmaster Tools: How to Set It Up and Read the Data
• What Is DKIM and How to Set It Up for Your Domain

The bottom line

One-click unsubscribe turns would-be spam complaints into clean opt-outs. Add List-Unsubscribe with an HTTPS URL and List-Unsubscribe-Post: List-Unsubscribe=One-Click, cover both with a valid DKIM signature, keep a visible link in the message, and honour every request within two days across all your systems.

FAQ

What is RFC 8058?

RFC 8058 is the standard that defines one-click unsubscribe using the List-Unsubscribe-Post header. It tells mail providers to unsubscribe a recipient with an HTTPS POST request, avoiding accidental unsubscribes by link scanners.

Do transactional e-mails need a List-Unsubscribe header?

No. Receipts, password resets and account alerts are transactional. The requirement applies to marketing and subscribed messages.

Is a mailto unsubscribe enough?

Not for one-click under current bulk sender requirements. An HTTPS URL with the List-Unsubscribe-Post header is needed; mailto can be added as an extra option.

Why doesn’t Gmail show the unsubscribe button for my mail?

Gmail decides when to display it, and may not show it for low-volume senders or every message. Check that both headers are present, covered by a passing DKIM signature and that the URL uses HTTPS.

How fast must I process unsubscribes?

Google and Yahoo expect requests to be honoured within two days. Many laws also require prompt processing, so immediate removal is the safest practice.

Can I ask people why they are unsubscribing?

Yes, on the confirmation page after the unsubscribe has been processed. The question must not be a condition for leaving the list.