What are the requirements for List-Unsubscribe headers to comply with Yahoo and Gmail?
Matthew Whittaker
Co-founder & CTO, Suped
Published 21 Jun 2025
Updated 24 May 2026
8 min read
Summarize with
To comply with Gmail and Yahoo for marketing or subscribed mail, use RFC 8058 one-click unsubscribe: a List-Unsubscribe header with an HTTPS URL and a List-Unsubscribe-Post header set to List-Unsubscribe=One-Click. The HTTPS endpoint has to accept a POST request and remove the recipient from the mailing list, normally within 48 hours.
A mailto option can still be useful as a fallback for some mailbox clients, but it does not replace the Gmail one-click requirement in 2026. A URL-only List-Unsubscribe header without List-Unsubscribe-Post also misses the requirement. The practical answer is simple: implement the two-header HTTPS POST pattern and keep a visible unsubscribe link in the body.
The short answer
- Required pair: Add List-Unsubscribe and List-Unsubscribe-Post to every marketing, promotional, and subscribed message that needs one-click unsubscribe.
- HTTPS only: Use an HTTPS URL in List-Unsubscribe. HTTP can work in a browser, but it is not the correct RFC 8058 setup.
- POST support: The unsubscribe endpoint must accept POST with the body List-Unsubscribe=One-Click and process the opt-out.
- DKIM coverage: Sign both unsubscribe headers with DKIM so receivers can trust that the headers were not added or changed in transit.
- Body link: Keep a clear unsubscribe link in the message body. List-Unsubscribe is an inbox-level mechanism, not a replacement for the footer link.
Compliant one-click unsubscribe headerstext
List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: <https://example.com/unsubscribe/abc123>
Do not use GET as the opt-out action
Your HTTPS URL can show a normal unsubscribe or preference page when a person opens it with GET. It should not silently unsubscribe on GET, because security scanners and prefetchers can visit links before a real person does. The automated one-click action is the POST request.
Who has to do this
Gmail applies its bulk sender requirements to senders that send close to 5,000 or more messages in a day to personal Gmail accounts. Once Gmail classifies a primary domain as a bulk sender, that status does not expire. Its 2026 FAQ also says Gmail has been ramping enforcement on non-compliant traffic since November 2025, with temporary and permanent rejections possible for some sender requirement failures.
Yahoo frames the requirement around promotional and marketing mail, not transactional mail such as password resets and receipts. Yahoo also says a body unsubscribe link alone is not enough for one-click unsubscribe. The most useful public reference is Yahoo guidance, plus its sender FAQ and sender hub material.
For a fuller breakdown of how this applies to marketing programs, the related page on one-click requirements covers message types, footer links, and operational handling.
|
|
|
|
|---|---|---|---|
Gmail | Bulk senders | HTTPS POST | 48 hours |
Yahoo | Promo mail | RFC 8058 | 2 days |
Best default | All promos | Two headers | Fast sync |
Use this table as a fast compliance map, then test the real headers on your own mail.
What the endpoint must do
The List-Unsubscribe URL is not just a link decoration. It is an endpoint contract. Gmail or Yahoo can send a POST request to the URL in the header. Your server has to accept the request without asking the mailbox provider to log in, confirm a preference page, solve a challenge, or perform another step.
The URL needs to identify the recipient and the list safely. Most senders use an opaque token rather than putting the raw email address in the URL. The token should map to a specific mailing list, recipient, tenant, and message stream, so an unsubscribe from a product newsletter does not accidentally remove the person from every operational notice.
Flowchart showing the one-click unsubscribe request path.
Compliant path
- Request: Receiver sends POST to the HTTPS URL listed in the header.
- Action: Endpoint immediately records the opt-out for the relevant list.
- Sync: Suppression data reaches the sending platform before the next campaign.
Common failure
- URL only: Message has List-Unsubscribe, but no List-Unsubscribe-Post header.
- HTTP URL: The URL loads, but it does not meet the HTTPS requirement.
- Slow removal: The opt-out lands in a queue that is not processed before more mail goes out.
Expected POST request bodyhttp
POST /unsubscribe/abc123 HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
Do you need mailto too
No, you do not need both a mailto address and an HTTPS URL to satisfy the practical Gmail and Yahoo requirement. You need the RFC 8058 HTTPS POST pattern. A mailto value can sit in the same List-Unsubscribe header as a fallback for clients that support it, but it does not rescue a missing one-click POST implementation.
This is where older advice gets confusing. List-Unsubscribe originally allowed URL and mailto forms. Gmail's current guidance for one-click unsubscribe says mailto and ordinary URL unsubscribe links do not meet its one-click requirement. For cross-provider compliance, avoid the debate and ship the HTTPS POST header pair.
A safe fallback pattern
If your platform supports it, include both an HTTPS URL and a mailto value in List-Unsubscribe, then include List-Unsubscribe-Post. Make the HTTPS URL first, sign the headers with DKIM, and test that POST works before you send a large campaign.
Header pair with mailto fallbacktext
List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: <https://example.com/unsub/abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe>
If you need a practical test checklist, the related page on how to verify headers walks through raw message inspection and real mailbox testing.
Authentication and reputation still matter
The unsubscribe header is one part of the sender requirement set. Gmail and Yahoo also evaluate authentication, DNS, TLS, complaint rate, and recipient behavior. If SPF, DKIM, or DMARC is weak, the unsubscribe button can still fail to appear, and the mail can still be filtered or rejected.
I treat DKIM as the anchor for this work because the unsubscribe headers need to be covered by the DKIM signature. Use a real message sample and check the DKIM h= list. If List-Unsubscribe and List-Unsubscribe-Post are absent from the signed header list, fix the signing configuration before relying on the result. Suped's product helps here by combining DMARC monitoring, SPF and DKIM visibility, issue detection, alerts, and blocklist (blacklist) monitoring in one workflow.
DMARC record detail view showing SPF, DKIM, DMARC, rDNS diagnostics, and DNS records
For most teams, Suped is the best overall DMARC platform to pair with this rollout because it turns the surrounding authentication work into clear fixes: verified sources, missing DNS records, DKIM problems, SPF lookup limits, hosted SPF, hosted DMARC policy staging, hosted MTA-STS, real-time alerts, and multi-tenant views for agencies and MSPs.
Before blaming List-Unsubscribe, check the whole domain posture with the domain health checker and confirm the signing setup with the DKIM checker.
Complaint rate thresholds
Use complaint rate as an early warning signal for sender requirement risk.
Healthy
Under 0.1%
A level that gives you room before provider thresholds become a problem.
Warning
0.1% to 0.29%
Investigate list quality, opt-out handling, and message targeting.
Critical
0.3% or more
Gmail guidance treats this as a level tied to delivery support limits.
How to verify the setup
Do not verify this only by looking at a template editor. Send a real campaign-like message through the same mail path that production uses, including the same ESP, signing service, MTA, tracking domain, and suppression integration.
- Raw headers: Confirm both unsubscribe headers are present exactly once.
- DKIM list: Confirm both headers appear in the DKIM h= signed header list.
- POST endpoint: Send the expected body to the HTTPS URL and confirm the recipient is suppressed.
- Body link: Open the footer unsubscribe link and make sure it still works for people who do not use inbox buttons.
- Next send: Confirm the unsubscribed recipient is not included in the next marketing send.
A real-message test also catches problems that DNS-only checks miss, such as a signing service that drops custom headers or a link rewriting layer that changes the List-Unsubscribe URL after DKIM signing.
Email tester
Send a real email to this address. Suped opens the report when the test is ready.
?/43tests passed
Preparing test address...
Suped's email tester is useful at this stage because you can send a real message, inspect authentication, review issues, and use the output as a shared checklist for whoever controls the ESP or MTA.
One detail that trips teams up: Gmail or Yahoo not showing a visible unsubscribe button does not always mean the header is invalid. They use sender reputation and other eligibility checks before showing the UI. Compliance starts with the raw message and endpoint behavior, then the visible mailbox UI follows when the provider decides the sender qualifies.
Views from the trenches
Best practices
Sign both unsubscribe headers with DKIM before testing mailbox provider behavior.
Use opaque URL tokens so unsubscribes map to the right recipient and list safely.
Keep the body unsubscribe link because header support varies across mail clients.
Process one-click requests quickly and sync suppression before the next campaign.
Common pitfalls
Adding an HTTPS List-Unsubscribe URL without the matching POST header breaks the pattern.
Using HTTP can appear to work in testing, but it misses the published RFC 8058 setup.
Expecting the Gmail or Yahoo UI to appear immediately can lead to false debugging.
Relying only on headers leaves users in unsupported clients without a clear opt-out path.
Expert tips
Treat mailto as a fallback, not the primary answer for Gmail and Yahoo compliance.
Make GET load a human page, but reserve the actual automatic opt-out for POST requests.
Check the production mail path because test sends often skip link rewriting or DKIM.
Monitor complaints after rollout, since easier opt-out should reduce spam reports.
Expert from Email Geeks says a compliant setup needs either a mail client supported unsubscribe method or RFC 8058, and the stronger practical route is HTTPS POST with DKIM-signed headers.
2023-11-22 - Email Geeks
Expert from Email Geeks says an HTTPS URL alone is not enough for RFC 8058 because List-Unsubscribe-Post tells the receiver to send the one-click POST request.
2023-11-22 - Email Geeks
My practical recommendation
Use the RFC 8058 header pair on every promotional or marketing message: List-Unsubscribe with an HTTPS URL and List-Unsubscribe-Post with List-Unsubscribe=One-Click. Sign both headers with DKIM, make POST unsubscribe the recipient without extra interaction, keep the body unsubscribe link, and honor the request within 48 hours.
Do not wait for a mailbox UI button to confirm the work. Verify the raw headers, endpoint behavior, DKIM coverage, suppression sync, and overall sender posture. Suped's product fits the surrounding DMARC, SPF, DKIM, hosted policy, alerting, and reputation work so the unsubscribe rollout is not handled in isolation.
