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 works | Mail client sends an email to the address on the recipient's behalf | Mailbox provider sends an HTTPS POST to your server |
| Meets RFC 8058 | No | Yes |
| Meets Gmail and Yahoo bulk rules | Not on its own | Yes |
| What you must build | A mailbox that is read and processed, ideally automatically | An 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.
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.
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.
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 dijitulHow 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.