📩 Email headers series. This is the tactical guide to the List-Unsubscribe and List-Unsubscribe-Post headers, including the one-click POST required by Gmail and Yahoo since February 2024. For the RFC catalog and other header deep-dives, see the headers and MIME hub →
🚪 Quick List-Unsubscribe reference
The List-Unsubscribe header tells the receiving mail client how to unsubscribe from your list without opening the message. Combined with List-Unsubscribe-Post, it enables the one-click unsubscribe button that Gmail and Yahoo require from any sender above 5,000 messages per day. Get the headers wrong and mail providers throttle you within days. The visible link that sits beside the header belongs in a properly built email footer.
| Specs | RFC 2369 (List-Unsubscribe), RFC 8058 (one-click POST) |
| Header 1 | List-Unsubscribe: mailto and/or https URL |
| Header 2 | List-Unsubscribe-Post: List-Unsubscribe=One-Click |
| Required for | Bulk senders over 5,000 messages/day to Gmail or Yahoo |
| Deadline | February 2024 (already in force) |
| Endpoint behavior | Must accept unauthenticated HTTPS POST, must complete unsubscribe with no user interaction |
List-Unsubscribe is the header that decides whether your unsubscribe button in Gmail actually works. It is not optional for bulk senders anymore: Google and Yahoo published sender requirements in October 2023 that took effect February 2024, and non-compliance means throttling, spam-folder placement, or outright blocking within days of exceeding the volume threshold. This guide covers the two RFCs, the exact header format, how to implement the POST endpoint correctly, and the 10 breakages that ship to production most often.
Why this header matters more than any other
Google and Yahoo’s bulk sender rules, effective February 2024, require any sender above 5,000 messages per day to a Gmail or Yahoo mailbox to implement a one-click unsubscribe. The one-click flow is enabled by two headers: List-Unsubscribe and List-Unsubscribe-Post. Without them, Gmail hides the “Unsubscribe” button from your messages entirely, and recipients who want to opt out click “Report spam” instead. Every spam complaint that could have been an unsubscribe raises your complaint rate closer to Gmail’s 0.3 percent hard ceiling.
The math is simple: a sender with 100,000 daily recipients and no one-click gets, conservatively, 200 to 500 spam-report clicks per day that would otherwise have been unsubscribes. That is a 0.2 to 0.5 percent complaint rate all by itself, before any legitimate spam complaints. This is why compliance is not optional; the alternative is a self-inflicted complaint rate that triggers the throttle.
RFC 2369: the base List-Unsubscribe header
Published in 1998, RFC 2369 defines a family of List-* headers for mailing lists. The relevant one for opt-out is List-Unsubscribe:
List-Unsubscribe: <mailto:unsubscribe@example.com>,
<https://example.com/unsubscribe?u=abc123>The value is one or more URIs in angle brackets, comma-separated. Two schemes are supported in practice:
- mailto: An email address the recipient can email to unsubscribe. Old-school and reliable; still recognized by every mail client.
- https: A URL the recipient can visit to unsubscribe. Modern mail clients render this as a button or link.
Include both. Mail clients pick whichever they prefer, and having both means your header works whether the client is a modern web-mail (which prefers HTTPS) or a legacy MTA that only understands mailto.
Format rules
- Each URI must be wrapped in angle brackets.
- URIs are comma-separated.
- The URI should be unique per recipient (so the unsubscribe action affects only that person).
- The URL should not require authentication or a captcha; the recipient may not have their credentials available in the mail client.
Uniqueness per recipient
The URL and mailto should include a token that uniquely identifies the recipient and the mailing list. A generic URL like https://example.com/unsubscribe is not useful; the recipient reaches your endpoint but you cannot tell who to unsubscribe. Use a signed token, an opaque UUID, or a per-recipient hash. Never encode the raw email address in a URL; that leaks the recipient’s address to whoever intercepts the URL.
RFC 8058: the one-click POST
RFC 8058 (published 2017) adds the one-click flow. Two changes:
- The recipient’s mail client sends an HTTP POST to the URL in List-Unsubscribe, not a GET.
- The sender confirms one-click support by adding a second header:
List-Unsubscribe-Post: List-Unsubscribe=One-Click.
Complete example headers for a compliant bulk send:
List-Unsubscribe: <mailto:unsub+abc123@sender.example.com>, <https://sender.example.com/unsub/abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickWhen Gmail sees List-Unsubscribe-Post with the one-click value, it renders the Unsubscribe button prominently. When the recipient clicks it, Gmail POSTs to the URL with a body of List-Unsubscribe=One-Click. Your endpoint must:
- Accept HTTPS POST at that URL.
- Read the recipient identifier from the URL path or query string.
- Complete the unsubscribe immediately, no user interaction.
- Return a 2xx response.
The recipient never sees a browser page; the mail client makes the request in the background. This is critical: the flow must succeed without any human clicking anything else after the initial Unsubscribe button.
Implementing the POST endpoint
Server-side, the endpoint is a straightforward HTTPS handler. Rough structure in pseudocode:
POST /unsub/<token>
1. Validate the token (signed, or looked up in a database).
2. Resolve the token to a (recipient_email, list_id) tuple.
3. Update the suppression list: add recipient_email to the do-not-send list for list_id.
4. Log the unsubscribe event with timestamp and source IP.
5. Return HTTP 200 with any body (Gmail does not read it).Key implementation rules:
- Accept POST, not just GET. The mail client sends POST per RFC 8058. Many web frameworks default to GET-only handlers; explicitly allow POST on this endpoint.
- No authentication required. The token itself is the authentication. Requiring a login, session cookie, or captcha breaks the one-click flow.
- Idempotent. The same token may be POSTed multiple times (Gmail may retry on failure). Do not error on second attempts; treat repeated POSTs as no-ops that still return 200.
- Fast. Complete the unsubscribe within a few seconds. Gmail’s timeout is around 30 seconds, but you want to be well under that. Push heavy processing (batch database writes, notification emails to internal teams) to an async queue and return 200 immediately.
- HTTPS only. RFC 8058 requires HTTPS. HTTP endpoints are ignored.
- No CORS or origin restrictions. Gmail POSTs from a Google IP with no browser context; adding
Access-Control-Allow-Originrestrictions or Referer checks blocks the request.
Testing your one-click flow
Manual test with curl
curl -X POST https://sender.example.com/unsub/abc123 \
-d "List-Unsubscribe=One-Click" \
-H "Content-Type: application/x-www-form-urlencoded"Expected: 2xx response, recipient added to suppression list.
Live test in Gmail
Send a test message to a Gmail account you control. Open the message. Gmail should show an “Unsubscribe” link next to the sender name at the top of the message. Click it, confirm the unsubscribe in the mailbox provider’s own confirmation dialog. Check that the recipient was added to your suppression list and no further messages were sent to that address.
What Gmail requires to show the button
- List-Unsubscribe header present with a valid HTTPS URL.
- List-Unsubscribe-Post header present with the exact value
List-Unsubscribe=One-Click. - The sender’s DMARC alignment passes (Gmail refuses to show one-click for unauthenticated mail).
- The sender’s complaint rate is below Google’s threshold (senders in throttle mode do not get the button until reputation recovers).
Google Postmaster Tools
The One-Click Unsubscribe compliance metric appears in Postmaster Tools once you cross the volume threshold. If it shows “Not compliant”, your headers are missing, malformed, or the POST endpoint is failing. See our Google Postmaster Tools guide for the full dashboard walkthrough.
The mailto: fallback
The mailto address in List-Unsubscribe is a fallback for clients that do not support the one-click POST. It also serves as a machine-readable unsubscribe path for old MUAs.
When a recipient’s mail client sends to the mailto address, your incoming mail infrastructure needs to parse the message and process the unsubscribe:
- Route the incoming address (
unsub+abc123@sender.example.com) to a parsing pipeline. - Extract the token from the local part.
- Look up the recipient and list.
- Update the suppression list.
- Optionally send a confirmation email back.
Most ESPs handle this automatically when you configure the mailto address in their dashboard. Self-hosted senders need to set up a subaddressing pattern in Postfix or Exim, or configure a catch-all forwarder to a parsing service.
10 common List-Unsubscribe mistakes
- Missing List-Unsubscribe-Post header. Without it, Gmail treats the URL as a legacy click-through, not one-click. The button may still appear, but it opens a browser window instead of executing the POST directly.
- POST endpoint only accepts GET. The most common bug. The endpoint URL from List-Unsubscribe is loaded fine in a browser but returns 405 Method Not Allowed on POST.
- Endpoint requires authentication or a captcha. Breaks the one-click flow entirely. The token itself is the only authentication needed.
- HTTP instead of HTTPS. RFC 8058 requires HTTPS. HTTP endpoints are ignored by Gmail and Yahoo.
- Generic URL without per-recipient token.
https://example.com/unsubscribegets the POST but has no way to identify who to unsubscribe. - Endpoint too slow. Synchronous database writes and downstream notifications timeout the POST. Return 200 fast, process asynchronously.
- CORS or Referer restrictions. Gmail POSTs from Google infrastructure with no browser context. Referer-check middleware blocks the request.
- Token in URL leaks the raw email address. Do not encode the recipient’s email in the URL. Use an opaque token or hash.
- Non-idempotent endpoint. Second POST returns an error, marking the whole flow as failed in Gmail’s eyes. Treat repeated POSTs as no-ops.
- List-Unsubscribe URL redirects. Some senders redirect the HTTPS URL to an internal marketing platform. Redirects break the one-click POST because the redirect target may not accept POST. Serve the endpoint at the final URL directly.
List-Unsubscribe FAQ
Is one-click unsubscribe mandatory for all senders?
Mandatory for senders above 5,000 messages per day to a single mailbox provider (Gmail, Yahoo, and increasingly Microsoft). Optional but recommended for lower-volume senders; recipients still see the Unsubscribe button when the headers are present, which reduces spam complaints. Effectively required for any sender doing marketing or transactional-with-preference-links email at scale.
Do I need both mailto and https in List-Unsubscribe?
Best practice, yes. Include both. Gmail and Yahoo prefer HTTPS with the one-click POST. Older mail clients, some corporate MTAs, and legacy MUAs prefer mailto. Having both gives every recipient a working path. The overhead of maintaining both is minimal and the coverage benefit is real.
Should the List-Unsubscribe URL confirm the unsubscribe with the user?
No. For the one-click POST specifically, the endpoint must complete the unsubscribe with zero user interaction beyond the initial button click. Gmail and Yahoo enforce this: an endpoint that requires a second confirmation click fails their compliance check. For the mailto fallback, a plain confirmation email back is acceptable but not required. Keep the flow frictionless.
How do I know if my endpoint is compliant?
Three checks. First, curl POST to your URL and verify it returns 2xx. Second, send a test message to your own Gmail account, click Unsubscribe, and verify the recipient was suppressed. Third, once you cross the 5,000-messages-per-day threshold, Google Postmaster Tools shows a One-Click Compliance metric that must read “Compliant”. If it shows non-compliant, the headers or endpoint are broken.
Does the recipient get a confirmation after unsubscribing via one-click?
Gmail shows an in-client toast confirming the unsubscribe. The sender should NOT send an email confirmation (“You have been unsubscribed”) because that email would violate the newly-recorded suppression. Complete the unsubscribe silently on your end. If you want to give the recipient a way to resubscribe or manage preferences, the message you sent them contains a link for that; do not use unsubscribe as an opportunity to send another message.
What about transactional email? Do I need List-Unsubscribe on password resets?
Not required by the Gmail and Yahoo rules for genuine transactional email (password resets, order confirmations, security alerts). Google’s guidance is that transactional messages, sent to a specific user in response to a specific action they took, do not need one-click. But if you also send marketing emails to the same recipient from the same domain, the marketing messages must have one-click, and mixing marketing content into transactional messages puts the whole domain at risk. Keep the streams separate.
Final words
List-Unsubscribe went from a nice-to-have to a compliance requirement in under a year. Sender rules from Gmail and Yahoo made one-click mandatory for anyone at scale, and the enforcement is real: senders who fail compliance see traffic throttled within days. The technical fix is small (two headers, one endpoint), but the operational payoff is large: every recipient who wants out has a friction-free path that does not go through the spam-report button.
The build order to keep: implement the POST endpoint first (idempotent, fast, HTTPS, no auth), add List-Unsubscribe with per-recipient tokens second, add List-Unsubscribe-Post third. Test with curl, then in Gmail, then verify in Postmaster Tools. All of it fits in an afternoon of engineering time.
For related deliverability topics, see our guides on the Gmail and Yahoo bulk sender rules, Google Postmaster Tools, and the Deliverability hub. For the underlying auth headers, see the Authentication-Results guide.
Fewer bad addresses on your list means fewer complaints, no matter how good your unsubscribe flow is.
SMTPing catches disposables, role-based, catch-all, syntax errors, dead mailboxes and traps before they even reach your suppression list. 13 validation types, 25 free daily.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
