What are the one-click unsubscribe requirements for Gmail and Yahoo, and how do they relate to CAN-SPAM compliance?
Michael Ko
Co-founder & CEO, Suped
Published 19 Apr 2025
Updated 24 May 2026
9 min read
Summarize with
The direct answer: Gmail and Yahoo require header-based one-click unsubscribe for bulk marketing and subscribed mail, and they also require a clearly visible unsubscribe link in the email body. The one-click requirement is about the mailbox-level unsubscribe action created by the List-Unsubscribe and List-Unsubscribe-Post headers, not every unsubscribe link in the email.
CAN-SPAM works differently. It requires a clear opt-out method in commercial email, lets senders use a preference menu, and still requires an option to stop all marketing messages. It does not turn every body unsubscribe link into an RFC 8058 one-click endpoint. I treat Gmail and Yahoo as deliverability requirements, and CAN-SPAM as the legal floor for commercial email in the United States.
- Header action: Use RFC 8058 with an HTTPS List-Unsubscribe URL and List-Unsubscribe-Post for the inbox unsubscribe button.
- Body link: Keep a visible footer link that opens a preference page or a simple unsubscribe page.
- Timing: Process Gmail and Yahoo unsubscribe requests within 48 hours, and CAN-SPAM requests within 10 business days.
What Gmail and Yahoo require
Gmail applies the bulk sender rules to senders that send around 5,000 or more messages per day to personal Gmail accounts. The threshold is counted at the primary domain level, so subdomains roll up. Once a sending domain has been classified as bulk, Gmail treats it as bulk going forward. Yahoo uses a similar bulk-sender framing and applies the unsubscribe requirement to marketing and subscribed messages.
For these messages, the required pattern is not just a footer link. The message needs a functioning list-unsubscribe header path that supports one-click unsubscribe, plus a visible body unsubscribe link. Gmail's current FAQ says a body link alone does not satisfy the one-click requirement. Yahoo says the same thing: body unsubscribe is useful, but the list-unsubscribe header is required for one-click compliance.
|
|
|
|
|---|---|---|---|
Who | Bulk senders | Bulk senders | Track volume |
Mail type | Marketing | Marketing | Exclude receipts |
Header | RFC 8058 | RFC 8058 | Use HTTPS |
Body link | Required | Required | Make visible |
Honor time | 48 hours | 2 days | Automate |
Compact view of the Gmail and Yahoo unsubscribe requirements.
Gmail message view showing a mailbox unsubscribe control and a body unsubscribe link.
A visible footer link does not replace RFC 8058 one-click unsubscribe for Gmail and Yahoo bulk sender compliance. I still include the footer link because it is expected by users, needed for CAN-SPAM-style opt-out paths, and useful when a mailbox client does not display its own unsubscribe control.
How CAN-SPAM fits
CAN-SPAM is not the same thing as Gmail and Yahoo's one-click requirement. The FTC CAN-SPAM guide says commercial messages need a clear and conspicuous opt-out explanation, and recipients must be able to opt out through a return email address or another easy internet-based method. It also says a preference menu is allowed, but there must be an option to stop all marketing messages.
That means a preference center can be compliant when it includes an obvious unsubscribe-all option and does not force account login, payment, extra personal data, or extra steps beyond the allowed opt-out path. A page that only lets someone reduce frequency, choose topics, or pause mail without a clear unsubscribe-all choice is the wrong design.
Gmail and Yahoo
- Main trigger: Bulk marketing or subscribed messages sent to their consumer mailbox users.
- Technical method: RFC 8058 one-click unsubscribe through message headers.
- Body link: Required, but it can open a preference center.
- Risk: Loss of delivery support, spam placement, temporary failures, and permanent rejections.
CAN-SPAM
- Main trigger: Commercial email where the primary purpose is advertising or promotion.
- Legal method: Clear opt-out by reply email or a single internet page.
- Preference menu: Allowed when unsubscribe-all is clearly available.
- Risk: Regulatory exposure, penalties, and liability for senders and parties involved.
For the common question about two clicks, I separate mailbox one-click from web-page confirmation. A mailbox one-click action should unsubscribe without a landing page. A body link can open a page with one obvious unsubscribe button. For a deeper treatment of that legal distinction, see two-click CAN-SPAM.
The header implementation I would ship
For a new implementation, I would ship an HTTPS RFC 8058 endpoint, not a new mailto-based path. Mailto is still accepted in some contexts, and existing systems do not need to remove it just to be neat. But HTTPS plus POST is cleaner for automation, easier to audit, and less dependent on mailbox-specific handling.
Marketing email headerstext
List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: <https://example.com/unsubscribe/u/abc123>
The POST request to that URL should unsubscribe the address from the list tied to that message without showing a confirmation page. The token in the URL should identify the recipient and list securely. Do not require login. Do not ask for a reason before honoring the opt-out. Do not make the endpoint depend on cookies, because mailbox clients are not normal browser sessions.
Expected one-click POST bodyhttp
POST /unsubscribe/u/abc123 HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
GET requests to the same URL should show a readable unsubscribe page, not silently unsubscribe. This matters because scanners, security tools, and curious users fetch URLs. I prefer using the same underlying token but treating POST and GET differently: POST records the one-click unsubscribe, while GET renders a page with a clear unsubscribe button.
Flowchart showing a header-based one-click unsubscribe request.
The clean pattern is one HTTPS list-unsubscribe URL, one RFC 8058 POST handler, and one visible footer link. The footer link can point to the same URL as a GET request, or to a preference center with an unsubscribe-all button.
What the visible unsubscribe link should do
The normal unsubscribe link in the email body does not have to be an inbox one-click link when the message already has compliant headers. It should be easy to find, readable, and accurate. I put it in the footer, often near the mailing address and preference links, and I make the unsubscribe-all choice more obvious than any save-the-subscription option.
A preference center is fine when it respects the user. The page can offer topic choices, frequency changes, or a pause option. It still needs a clear path to stop all marketing messages. The preference center cannot bury that action behind login, a survey, or a dark pattern.
- Good page: Shows the address being unsubscribed and one clear button to stop all marketing mail.
- Bad page: Requires login before the recipient can submit the opt-out request.
- Good menu: Offers newsletter choices and includes an unsubscribe-all option on the same page.
- Bad menu: Only lets the recipient change categories and never stop all commercial mail.
Unsubscribe timing thresholds
How I treat response timing when designing suppression workflows.
Best practice
Immediate
Suppress before the next campaign leaves.
Mailbox rule
48 hours
Gmail and Yahoo expect fast processing.
CAN-SPAM maximum
10 business days
The legal outer limit for commercial mail.
For GET and POST handling details, the practical split is simple: POST is the non-interactive mailbox action, and GET is the user-readable web page. I would not silently unsubscribe on GET because automated link checks can trigger false opt-outs. The deeper implementation question is covered in GET vs POST.
How I test the full path
I test this in two layers. First, I inspect the message headers and body to confirm that the headers are present, the HTTPS URL is valid, the body link is visible, and the footer wording is not confusing. A quick pass through the email tester is useful here because it gives me a single report for the message.
Email tester
Send a real email to this address. Suped opens the report when the test is ready.
?/43tests passed
Preparing test address...
Second, I send real test mail to Gmail and Yahoo inboxes and click the mailbox unsubscribe action when it appears. The test is not complete until the suppression list changes, the recipient stops receiving that stream, and the next campaign excludes the recipient. I also test the visible body link separately because that path has different browser behavior and different analytics.
Email tester sample report showing total score, email preview, issue summary, and per-section results
Header compliance also depends on the broader sender setup. Gmail and Yahoo requirements sit next to SPF, DKIM, DMARC, reverse DNS, TLS, and complaint-rate expectations. Suped's domain health checker helps check that foundation before I focus on the unsubscribe path.
Gmail and Yahoo do not always show their unsubscribe UI just because the headers exist. Reputation, engagement, authentication, and automated checks affect whether the mailbox control appears. Treat header presence as necessary, then verify real mailbox behavior.
Where Suped fits
Suped is relevant because one-click unsubscribe is only one part of the Gmail and Yahoo sender package. The same domains need reliable SPF, DKIM, DMARC, low complaint rates, clean routing, and fast visibility when something changes. Suped brings DMARC, SPF, DKIM monitoring, hosted DMARC, hosted SPF, SPF flattening, blocklist (blacklist) monitoring, real-time alerts, and issue-specific fix steps into one workflow.
For most teams, Suped is the strongest practical choice when the goal is ongoing compliance rather than a one-time header check. The value is the daily operating loop: detect authentication issues, see which sources are sending, catch unverified senders, monitor reputation, and keep policy changes controlled. That matters when Gmail and Yahoo enforcement affects real delivery.
Issue steps to fix dialog showing the issue overview, tailored fix steps, and verification action
I would still verify the unsubscribe endpoint inside the sending platform or application that owns it. Suped does not magically process a POST endpoint in your product. What it does well is monitor the authentication and delivery side around that implementation, including DMARC monitoring, source visibility, and fix guidance when the domain setup starts drifting.
Views from the trenches
Best practices
Use HTTPS RFC 8058 for new systems and keep mailto only for legacy compatibility.
Process POST opt-outs before the next campaign and keep audit logs for each request.
Keep the visible footer link readable and include unsubscribe-all beside preferences.
Test Gmail and Yahoo inbox behavior with real messages, not just raw header checks.
Common pitfalls
Assuming a footer link alone satisfies Gmail and Yahoo one-click header requirements.
Letting GET requests silently unsubscribe users after security scanners visit links.
Hiding unsubscribe-all inside a preference center focused only on retention choices.
Treating CAN-SPAM timing as enough when mailbox providers expect faster action from senders.
Expert tips
Separate POST and GET behavior so mailbox actions and browser visits are both clean.
Use opaque tokens that map to recipient and list without exposing personal data.
Track unsubscribe source so body links and mailbox actions can be analyzed apart.
Monitor authentication health because unsubscribe compliance cannot fix weak trust.
Expert from Email Geeks says the requirement is a non-interactive list-unsubscribe path plus a visible body unsubscribe link.
2024-01-18 - Email Geeks
Expert from Email Geeks says new systems should prefer HTTPS and RFC 8058 POST over building fresh mailto handling.
2024-01-18 - Email Geeks
The practical answer
The safest implementation is straightforward. Put RFC 8058 headers on marketing and subscribed mail, make the POST endpoint unsubscribe the recipient without extra interaction, keep a visible body unsubscribe link, and ensure the body path gives people a clear way to stop all marketing mail.
Gmail and Yahoo are asking for mailbox-level one-click unsubscribe. CAN-SPAM is asking for a clear legal opt-out path for commercial email. They overlap, but they are not identical. Build for both: fast non-interactive POST handling for mailbox providers, and a clean user-facing page that respects the recipient's choice.
The most common mistake is treating this as a copywriting issue in the footer. It is really a message-header, endpoint, suppression, and compliance workflow. Once those pieces are connected, the footer link and preference center become support paths instead of the only opt-out mechanism.
