What are the requirements for one-click unsubscribe in email marketing?
Updated on 27 Oct 2026: We clarified unsubscribe deadlines and CAN-SPAM rules, with practical checks for signed headers and suppression.
The requirement for one-click unsubscribe in email marketing is header-based. It is not a rule that every visible unsubscribe link in the email body must instantly remove someone after a link scanner visits it. For Gmail bulk sender compliance, and for a shared setup that also fits Yahoo's bulk sender expectations, the practical requirement is RFC 8058: add a List-Unsubscribe header with an HTTPS URL, add List-Unsubscribe-Post with the exact one-click value, sign those headers with DKIM, accept an HTTP POST at the unsubscribe endpoint, and honor the opt-out without another user action.
Separate this into two unsubscribe paths. The header path is the mailbox-provider one-click path. The footer path is the human-facing path, and it can still lead to a preference center or confirmation page. That split matters because many security tools still prefetch or scan normal links in the message body, while the RFC 8058 flow uses a POST request to distinguish the unsubscribe action from ordinary link fetching.
For email marketing teams, the answer is direct: implement the header flow on marketing and subscribed messages, keep a clear unsubscribe link in the body, process the request fast, and test the final message after the ESP, MTA, and DKIM signer have all touched it.
Who needs one-click unsubscribe
Gmail applies the requirement to senders that send close to 5,000 messages or more in a 24-hour period to personal Gmail accounts. Messages from the same primary domain count together, and Gmail says a domain that crosses the threshold is treated as a bulk sender permanently. The Gmail rule applies to personal Gmail accounts, not inbound Google Workspace mailbox policy, but any sender reaching personal Gmail inboxes at that volume should treat one-click unsubscribe as mandatory for marketing and subscribed mail. See Google's sender FAQ.
Yahoo's bulk sender rules also require a functioning list-unsubscribe header, a visible in-body unsubscribe link, and unsubscribe processing within 2 days for marketing and subscribed messages. Yahoo does not publish a numerical bulk-sender threshold, so do not apply Gmail's 5,000-message threshold to Yahoo. Yahoo's sender requirements accept mailto and highly recommend RFC 8058. HTTPS POST is the shared implementation that satisfies Gmail's one-click requirement and avoids accidental GET opt-outs.
- Include it: Use one-click headers for newsletters, promotional campaigns, lifecycle nudges, win-back sends, product announcements, and subscribed content digests.
- Transactional messages: Pure password resets, receipts, account security alerts, reservation confirmations, and form submission confirmations are excluded from the marketing one-click requirement.
- Split mixed templates: If a transactional message includes an offer, separate the offer into marketing mail or give that marketing stream its own unsubscribe scope.
- Apply it to future sends: You cannot retroactively add headers to mail already sitting in inboxes, so fix the next send and keep suppression consistent.
Current enforcement
Google began ramping up enforcement on non-compliant traffic in November 2025. Its sender FAQ says missing one-click unsubscribe does not automatically cause rejection or spam placement. It does make bulk senders ineligible for delivery mitigation, as does failing to honor unsubscribe requests within 48 hours. Failures of other sender requirements can lead to temporary or permanent rejections.
RFC 8058 one-click unsubscribe requirements
A compliant one-click unsubscribe setup has a small number of moving parts, but each one has to survive the actual sending path. Check the final received message, not the template editor, because headers can be rewritten, folded, removed, or left out of the DKIM signature after the message leaves the marketing system. RFC 8058 defines the header syntax and POST behavior.
- Header pair: Include exactly one List-Unsubscribe header and exactly one List-Unsubscribe-Post header in the message.
- HTTPS endpoint: Include exactly one HTTPS URL in angle brackets, with enough opaque data to identify the recipient and list. A mailto value can be additional, but it does not replace the HTTPS URL for Gmail's RFC 8058 flow.
- POST handling: Unsubscribe when a valid POST carries the form field List-Unsubscribe=One-Click. Do not require additional form fields.
- POST encoding: Accept both application/x-www-form-urlencoded and multipart/form-data requests.
- DKIM coverage: Include both unsubscribe headers in the h= tag of at least one valid DKIM signature. A DKIM pass on a signature that omits those headers is insufficient.
- Fast suppression: Process requests immediately where practical and within 48 hours for a shared Gmail and Yahoo setup. Yahoo requires 2 days; Gmail recommends 48 hours and uses that window for delivery mitigation eligibility.
- Visible link: Keep a clear in-body unsubscribe link for users who do not use the mailbox provider's header UI.
Minimum RFC 8058 header exampletext
List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: <https://unsubscribe.example.com/u/aB9xQ2>
Do not treat a normal GET as consent
A mailbox provider's one-click action arrives as POST. Do not remove a subscriber after a normal browser visit, link scanner request, or prefetch request to the unsubscribe URL. This is the main protection against accidental unsubscribes.
Header one-click versus footer unsubscribe
The confusing part is the phrase "one-click unsubscribe" itself. People use it to mean a legal opt-out path, a link in the footer, a mailbox provider button, or a preference center. For Gmail and Yahoo sender requirements, the important meaning is the mailbox provider button created from List-Unsubscribe headers.
That means a footer link can still be two-step in a narrow sense. It can take the person to a single page showing the subscribed address and a button to confirm unsubscribing or choose fewer messages, subject to applicable opt-out laws. The header path is the one that needs to complete without extra steps after the mailbox provider sends the POST. The distinction is covered in more detail in GET versus POST.
Header one-click
- Trigger: The mailbox provider shows an unsubscribe action in the inbox UI.
- Method: The provider sends an HTTP POST to the HTTPS URL in the header.
- Result: The recipient is suppressed from that list without a login, form, or extra click.
Footer unsubscribe
- Trigger: The user clicks the visible link inside the marketing email.
- Method: The link opens a web page, often a preference center or confirmation screen.
- Result: The user can leave one list, reduce frequency, or opt out of all marketing.
Flowchart showing one-click unsubscribe headers, DKIM validation, POST handling, and suppression.
Choose the unsubscribe scope
One-click unsubscribe removes the recipient from the mailing list associated with the message. It does not automatically suppress every promotional message from the sender. Decide the scope before sending, encode that scope in the opaque URL token, and apply the result across every system that can send the affected stream.
|
|
|
|---|---|---|
Weekly newsletter | Weekly newsletter list | Other opted-in streams continue |
Product updates | Product updates list | Newsletter consent is unchanged |
All-marketing stream | All marketing | Promotional sends stop across systems |
Preference center link | User-selected scope | Selections apply after confirmation |
Examples of one-click unsubscribe scope
Freeze scope at send time
The token should preserve the list or consent scope attached to the message when it was sent. If a campaign is renamed or moved later, an unsubscribe from the older message must still change the original subscription represented by that message.
How CAN-SPAM opt-out rules differ
Mailbox-provider requirements and email unsubscribe laws apply separately. The FTC's CAN-SPAM guidance covers U.S. commercial email, including business-to-business email, even below Gmail's bulk-sender threshold. Its unsubscribe rules include:
- Honor opt-out requests within 10 business days. Use the shorter 48-hour provider window when sending bulk marketing mail to Gmail and Yahoo.
- Keep the opt-out mechanism working for at least 30 days after sending. Unsubscribe token expiry must not cut that period short.
- Do not charge a fee, require a login or mandatory survey, or make recipients visit multiple web pages to complete an opt-out.
- Offer an option to stop all marketing messages from the sender, even when a preference center also offers individual list choices.
Show confirmation after recording the opt-out, and keep feedback or frequency preferences optional. A list-specific RFC 8058 action does not replace the all-marketing opt-out required by CAN-SPAM.
Header and endpoint checklist
Use this checklist when reviewing a marketing program because most failures are small implementation details. The headers look present, but the URL is not HTTPS. The endpoint works in a browser, but ignores POST. DKIM passes, but the unsubscribe headers are not in the signed header list. Any of those can stop the mailbox provider from showing or trusting the one-click option.
|
|
|
|---|---|---|
Header pair | Exactly one of each header | POST header missing or duplicated |
URL | One HTTPS endpoint | Mailto-only or HTTP-only link |
Method | Accepts POST | GET unsubscribes |
Payload | One-click value accepted | Wrong body ignored |
Encoding | Accepts both RFC encodings | Only one content type works |
DKIM | Both fields in a valid signature's h= tag | Fields unsigned |
Response | Direct success response | HTTPS redirect returned |
Timing | Immediate or within provider window | Slow batch job |
Scope | Marketing list tied to message | Wrong list suppressed |
Compact checklist for one-click unsubscribe implementation
The endpoint should validate a signed or opaque token, identify the subscriber and list, accept both application/x-www-form-urlencoded and multipart/form-data, record the event, update suppression, and return a direct success response. It must not depend on cookies or HTTP authorization, and RFC 8058 says not to return an HTTPS redirect. It should not require a login, CAPTCHA, reason selection, or page load before accepting the opt-out.
Processing time targets
Treat immediate suppression as the operating target. Yahoo requires processing within 2 days; Gmail recommends 48 hours and makes that window a condition for delivery mitigation.
Internal target
0-15 min
Suggested operating target for suppression, not a provider requirement.
Operational buffer
Same day
The request is completed well before provider timing limits.
Provider window
Within 48 hours
Meets Yahoo's deadline and Gmail's unsubscribe timing condition for mitigation.
Late
Over 2 days
Misses Yahoo's deadline and Gmail's unsubscribe timing condition for mitigation.
Authentication and sender compliance
One-click unsubscribe is part of the broader Gmail and Yahoo sender requirements. RFC 8058 relies specifically on a valid DKIM signature that covers both unsubscribe headers. Bulk senders also need SPF and DKIM, a published DMARC policy with an aligned authentication pass, low complaint rates, valid DNS, and standards-compliant message formatting.
Suped is our DMARC reporting and email authentication platform. Use Suped to review reported SPF and DKIM results during the rollout while the marketing system handles the unsubscribe endpoint and suppression records. DMARC aggregate reports do not show whether a DKIM signature covers the unsubscribe headers, so inspect the received message for that check.
A practical workflow is simple: confirm authentication with DMARC monitoring, run a domain health check, send a real marketing test, inspect the raw headers, then confirm that the POST endpoint writes to the same suppression system used by your campaign tool.
Suped DMARC dashboard showing email volume, authentication health, and source breakdown
One-click does not replace DMARC
A working unsubscribe flow helps reduce frustration and spam complaints, but it does not repair authentication. Gmail and Yahoo bulk senders still need SPF and DKIM, a DMARC policy with an aligned SPF or DKIM pass, low complaint rates, valid forward and reverse DNS, and messages that follow applicable format standards.
How to test one-click unsubscribe
Testing has to happen on the finished email. A staging template that contains the right header names does not prove the production message is compliant. Send to real inboxes, view the original message, and inspect the exact headers after all signing and routing steps are complete.
Send a copy through Suped's email tester so the authentication, headers, and message structure can be reviewed together. The goal is to prove the headers are usable, signed, and connected to a live suppression path.
Email tester
Send a real email to this address. Suped shows a results button when the test is ready.
?/43tests passed
After that, check the server logs for a POST request when a mailbox-provider unsubscribe action is used. The form data should contain the one-click value. The endpoint should update the list or suppression table without requiring the user to open a browser. A separate testing checklist is useful when several teams share responsibility for templates, DNS, signing, and suppression.
Example POST for a dedicated test subscriptionhttp
POST /u/aB9xQ2 HTTP/1.1 Host: unsubscribe.example.com Content-Type: application/x-www-form-urlencoded Content-Length: 26 List-Unsubscribe=One-Click
Do not judge compliance only by whether Gmail shows the unsubscribe control at the top of the message. Gmail applies eligibility checks before displaying that control, so raw headers, DKIM coverage, endpoint logs, and suppression records are the better proof.
Email tester sample report showing total score, email preview, issue summary, and per-section results
- Send test: Send the same production template through the same production mail stream.
- View source: Confirm exactly one of each unsubscribe header is present in the received message.
- Check DKIM: Confirm at least one signature passes and includes both unsubscribe headers in its h= tag.
- Test POST: Use the mailbox provider action when available, or submit a POST for a dedicated test subscription, and confirm receipt in the endpoint logs.
- Verify suppression: Confirm the address is excluded from the next send in the affected marketing stream, including messages already queued.
Also confirm that GET requests leave the subscription unchanged and that repeated valid POST requests succeed without reversing the opt-out. A contact import or CRM sync must not restore marketing eligibility without a new subscription.
Secure the unsubscribe endpoint
The header endpoint should only unsubscribe on a valid POST. The visible footer page should help humans understand what they are changing. That page can show the address from the token, offer list-level choices, and include an all-marketing opt-out.
Do not ask the user to type an email address into the unsubscribe page. The link should identify the original recipient. Letting people type any address creates abuse and support problems. If the address is shown, it should be read-only or partially masked, with the action tied to the signed token.
A clean endpoint pattern
- Token: Use an opaque, hard-to-forge token that identifies the subscriber and list. Keep it valid for the applicable opt-out period, including at least 30 days after sending under CAN-SPAM.
- Validation: Reject malformed tokens and log the reason without exposing personal data.
- Suppression: Write to the suppression source used by all campaign sends.
- Response: Return a simple success status and avoid redirects in the POST path.
For Gmail and Yahoo bulk sending, the broader Gmail and Yahoo requirements also matter. One-click unsubscribe is one line item in a larger sender compliance set that includes authentication, complaint control, and sending only mail that people asked to receive.
Practical unsubscribe tips
Best practices
Treat RFC 8058 as a header workflow, separate from the visible unsubscribe link in the email body.
Process POST requests quickly and record the list, address, timestamp, and source system.
Keep the body unsubscribe link useful for preferences, with a clear way to stop all marketing.
Common pitfalls
Do not unsubscribe on GET requests, because security scanners still test normal links.
Do not ask users to type an address; the signed token should identify the recipient.
Do not ship headers without DKIM coverage, because receivers can ignore unsigned fields.
Expert tips
Keep opaque unsubscribe tokens valid long enough for recipients to act on older messages.
Test the raw headers after every template or ESP migration, not just the landing page.
Monitor complaint rate after rollout; broken unsubscribe flows create spam reports fast.
