Home / Guides / Requirements

List-Unsubscribe and one-click unsubscribe (RFC 8058)

The two headers behind the unsubscribe button in Gmail and Yahoo, how the POST request works, and how to set it up correctly on your platform or your own code.

7 min read · Updated 27 October 2026 · By the dijitul team

One-click unsubscribe is the "Unsubscribe" link Gmail, Yahoo and others show next to the sender's name. It is driven by two email headers, List-Unsubscribe and List-Unsubscribe-Post, defined in RFC 8058. Since February 2024 Gmail and Yahoo have required it on marketing mail from bulk senders, and requests must be honoured within 2 days. Done properly, it also reduces spam complaints, because people who want to leave have an easier option than the "Report spam" button.

The two headers

A correctly set up marketing email carries both of these headers:

List-Unsubscribe: <https://example.co.uk/unsubscribe?u=8f3a91c2&l=news>, <mailto:unsubscribe@example.co.uk?subject=unsubscribe-8f3a91c2>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe

This header is much older (RFC 2369). It lists one or more ways to unsubscribe, each wrapped in angle brackets and separated by commas. For one-click unsubscribe it must include an HTTPS URL. A mailto address can sit alongside it as a fallback for mail clients that only understand the older method.

List-Unsubscribe-Post

This header must contain exactly List-Unsubscribe=One-Click. It tells the mailbox provider that it can unsubscribe the recipient by sending a POST request to the HTTPS URL, with no web page and no confirmation step. Without it, the HTTPS URL is treated as an ordinary link that a person has to open in a browser.

Mailto versus HTTPS

mailto:https: with List-Unsubscribe-Post
How it worksMail client sends an email to the address on the recipient's behalfMailbox provider sends an HTTPS POST to your server
Meets RFC 8058NoYes
Meets Gmail and Yahoo bulk rulesNot on its ownYes
What you must buildA mailbox that is read and processed, ideally automaticallyAn endpoint that accepts POST and unsubscribes immediately

The sensible setup is both: HTTPS for one-click, mailto as a fallback. If you include a mailto address, it must actually work. An unmonitored inbox that silently drops requests is worse than no mailto at all.

What the POST request looks like

When someone clicks Unsubscribe in Gmail, Google's servers (not the recipient's browser) send a request like this to the URL in your header:

POST /unsubscribe?u=8f3a91c2&l=news HTTP/1.1
Host: example.co.uk
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

List-Unsubscribe=One-Click

Your endpoint has to deal with that request on its own. In practice that means:

  • Identify the subscriber from the URL. No cookies or login session will be sent. Put an opaque token in the URL that maps to the subscriber and list. Do not put a plain email address in the URL.
  • Unsubscribe straight away. No "are you sure?" page, no preference centre, no login. The POST itself is the confirmation.
  • Return a 2xx response. A 200 or 202 with a short body is fine. Do not redirect.
  • Handle GET separately. Some clients and people will open the same URL in a browser. A GET can show a page with a confirm button or a preference centre, but must not unsubscribe on its own, because link scanners and security tools fetch URLs automatically and would unsubscribe people by accident.
  • Make tokens hard to guess. Use a long random value or a signed token so nobody can unsubscribe other people by changing the URL.
Test your endpoint with curl before you go live: curl -X POST -d "List-Unsubscribe=One-Click" "https://example.co.uk/unsubscribe?u=TESTTOKEN&l=news" should return a 2xx status and the test subscriber should be marked unsubscribed.

DKIM must cover both headers

RFC 8058 requires the message to carry a valid DKIM signature that covers both List-Unsubscribe and List-Unsubscribe-Post. Otherwise anyone could forge a message with an unsubscribe URL of their choosing. In the DKIM signature, both header names must appear in the h= tag:

DKIM-Signature: v=1; a=rsa-sha256; d=example.co.uk; s=mail2026;
    h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
    bh=...; b=...

This is a frequent cause of "we added the headers but Gmail ignores them". It happens when headers are injected after signing, for example by a plugin or relay that adds them on the way out, or when the signer's header list was never updated. The signature should also be from your own domain (or one aligned with your From address) so that it supports DMARC. See the DKIM guide for how signing works.

Check your setup now: run a free test at mail-tester.co.uk and see your score in seconds.

Honour requests within 2 days

Gmail and Yahoo require unsubscribe requests to be processed within 2 days. In practice, treat the POST as instant: mark the subscriber as unsubscribed in the same request. The 2-day window exists for senders whose lists are synchronised between systems, for example a CRM that pushes to an email platform overnight. If that is you, check the sync actually carries unsubscribes across and that no scheduled campaign goes out to someone who left yesterday.

The biggest real-world failure is not the headers, it is the list. If someone unsubscribes in your email platform but your CRM re-imports them the next week, you are breaking the rules and will generate exactly the spam complaints this system is meant to prevent. Make your unsubscribe list the master record and suppress against it everywhere.

Transactional versus marketing mail

The requirement applies to marketing and subscribed bulk mail: newsletters, promotions, product announcements, automated nurture sequences. It does not apply to transactional messages that a person needs because of something they did, such as:

  • order confirmations, receipts and invoices
  • password resets and login codes
  • shipping and appointment notifications
  • account security alerts

Be honest about the line. A receipt with a large promotional block underneath is drifting into marketing. If you are unsure, add the headers anyway: there is no penalty for offering one-click unsubscribe on borderline mail, but you will want to unsubscribe people from the marketing stream only, not from their receipts.

The Gmail rules apply in full to bulk senders (those sending roughly 5,000 or more messages a day to Gmail addresses), but there is no reason to wait until you reach that size. Smaller senders benefit from fewer complaints too. Microsoft has also tightened its expectations for high-volume senders to Outlook.com; see the Outlook sender requirements guide.

Platform settings

Most reputable email marketing platforms add both headers automatically to campaign mail, signed with DKIM. What you need to check:

  • Custom domain authentication is set up. If the platform signs with its own domain rather than yours, your DMARC alignment and reputation suffer. Set up the DKIM records the platform gives you.
  • The headers are on every marketing send, including automated journeys and API-triggered campaigns, not just newsletters sent from the editor.
  • Transactional streams are separated. Many platforms have a separate transactional or "operational" mode that leaves the headers off. Make sure marketing mail does not go through it.
  • Unsubscribes sync back to your CRM, e-commerce platform or wherever else you send from.

If you send from your own application (a WordPress plugin, a custom script via SMTP or an API), you will usually have to add the headers yourself, build the endpoint, and make sure your signing happens after the headers are added. Many transactional email APIs let you pass custom headers per message; check that they are included in the DKIM signature in the delivered message.

Web design & SEOdijitulA Mansfield web design and SEO agency since 2006. Websites that get found and turn visitors into customers.Talk to dijitul

How to check your headers

Send a real campaign (not a platform "test send", which sometimes skips the headers) to a Mail Tester UK address. The report shows whether List-Unsubscribe and List-Unsubscribe-Post are present, whether the URL is HTTPS, and whether DKIM passes. You can also open a delivered message in Gmail, choose "Show original", and search for the two headers and the h= list in the DKIM signature.

For the rest of the requirements that came in alongside one-click unsubscribe, including authentication and spam rate limits, read the Gmail and Yahoo sender requirements guide.

Frequently asked questions

What is one-click unsubscribe?

It is a standard (RFC 8058) that lets a mailbox provider unsubscribe someone on their behalf with a single HTTPS POST request, without the recipient visiting a web page or confirming anything. It uses the List-Unsubscribe and List-Unsubscribe-Post headers.

Is one-click unsubscribe required?

Gmail and Yahoo have required it for marketing and subscribed bulk mail since February 2024, and unsubscribe requests must be honoured within 2 days. It is not required for purely transactional messages such as receipts and password resets.

Is a mailto List-Unsubscribe enough?

No. A mailto address is still useful as a fallback, but RFC 8058 one-click unsubscribe needs an HTTPS URL plus the List-Unsubscribe-Post header. A mailto link alone does not meet the Gmail and Yahoo bulk sender rules.

Why isn't Gmail showing the unsubscribe link for my emails?

Gmail decides when to show it based on the headers being present and valid, DKIM covering them, and your sending reputation. New or low-volume senders may not see the link even when everything is correct.

Do I still need an unsubscribe link in the email body?

Yes. The headers are an addition, not a replacement. Keep a clear, visible unsubscribe link in the footer of every marketing email.

From the team behind Mail Tester UK

More from dijitul