# One-click unsubscribe (RFC 8058): how to set it up and test it URL: https://iblockspam.com/blog/one-click-unsubscribe-rfc-8058 Last updated: 2026-10-09 Published: 2026-10-09 Topic: Running email day to day Author: iBlockSpam Team > How RFC 8058 one-click unsubscribe works: the List-Unsubscribe and List-Unsubscribe-Post headers, Gmail and Yahoo rules, DKIM coverage and how to test it. ## Short answer One-click unsubscribe, defined in RFC 8058, adds two headers to marketing mail: List-Unsubscribe with an HTTPS URL and List-Unsubscribe-Post: List-Unsubscribe=One-Click. The mailbox provider POSTs to that URL when a recipient clicks Unsubscribe. The message must be DKIM-signed over both headers, and Gmail and Yahoo expect bulk senders to honor requests within two days. When a Gmail or Yahoo user clicks their mailbox's own Unsubscribe button, the provider needs a reliable way to tell you. RFC 8058 defines it: two email headers and an HTTPS endpoint that accepts a POST. Since 2024, both providers have required it from bulk senders for marketing mail. This guide explains the headers, the rules, and how to test your setup. ## What is one-click unsubscribe? The original `List-Unsubscribe` header comes from [RFC 2369](https://www.rfc-editor.org/rfc/rfc2369.html), published in 1998. It lets a message carry the address or URL that unsubscribes the recipient, so mail software can offer an unsubscribe button. RFC 2369 lists the URLs in angle brackets, separated by commas, in order of preference: ``` List-Unsubscribe: , ``` That header alone has a problem. An HTTPS link usually opens a web page that asks the user to confirm, and anything that fetches the link automatically, such as a security scanner, could trigger it. [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html), published in 2017, fixes this with a second header that says the URL accepts a one-click POST: ``` List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` When the recipient clicks the provider's Unsubscribe button, the provider sends an HTTPS POST to the URL with `List-Unsubscribe=One-Click` as the body. Your server removes the recipient, with no page, form or login involved. ## Why does it use POST instead of a normal link? RFC 8058 says it directly: "anti-spam software often fetches all resources in mail header fields automatically." A GET request is what a scanner sends when it checks a link for malware. If a GET unsubscribed people, recipients would be dropped from lists they never left. A POST with a fixed body is not something scanners normally send, so it's a much stronger signal that a person asked. The RFC also limits the POST to that single key and value, so an attacker can't use the mechanism to submit arbitrary forms on someone else's website. ## What do Gmail and Yahoo require? | Rule | Gmail | Yahoo | |---|---|---| | Who it applies to | Bulk senders (close to 5,000 or more messages a day to personal Gmail accounts) | Bulk senders (no volume threshold published) | | Which mail | Marketing and subscribed messages; transactional messages excluded | Promotional and marketing messages | | Header method | One HTTPS URL plus List-Unsubscribe-Post; mailto alone doesn't qualify | List-Unsubscribe header, "preferably according to RFC 8058" | | Body link | Clearly visible unsubscribe link also required | A body link alone isn't enough | | Processing time | Within 48 hours recommended | Within 2 days | | In force since | June 1, 2024 for senders with existing unsubscribe links | Enforcement began June 2024 | Sources: Google's [sender guidelines](https://support.google.com/mail/answer/81126) and [FAQ](https://support.google.com/mail/answer/14229414), Yahoo's [best practices](https://senders.yahooinc.com/best-practices/) and [FAQs](https://senders.yahooinc.com/faqs/). Two details catch people out: - **Google doesn't accept mailto for one-click.** Its FAQ says: "We'll continue to support mailto links but they don't meet our one-click unsubscribe requirement." You need the HTTPS URL. A mailto address can stay in the header as a fallback. - **Gmail bulk status is permanent.** Google says senders who meet the bulk criteria at least once are permanently considered bulk senders, so a single large campaign brings these rules into play for good. For the full set of sender rules, including authentication and spam rates, see our guide to [Gmail, Yahoo and Microsoft bulk sender requirements](https://iblockspam.com/blog/gmail-yahoo-microsoft-bulk-sender-requirements). ## What does RFC 8058 require from the sender? Sections 3.1 and 4 of the RFC set out the sender's obligations. In plain terms: 1. **One HTTPS URL.** The `List-Unsubscribe` header "MUST contain one HTTPS URI." It may contain other URIs, such as mailto. 2. **The exact Post value.** `List-Unsubscribe-Post` must contain the single pair `List-Unsubscribe=One-Click`. 3. **A self-contained URL.** The URL "MUST contain enough information to identify the mail recipient and the list." It should include an opaque or hard-to-forge token, and your server should check that token. 4. **No cookies or login.** The provider's POST "MUST NOT include cookies, HTTP authorization, or any other context information." Your endpoint must work without them. 5. **No redirect.** "The mail sender MUST NOT return an HTTPS redirect." Return a success response directly. 6. **DKIM coverage.** The message must carry at least one valid DKIM signature, and both headers "MUST be covered by the signature and included in the 'h=' tag." If they aren't, the RFC says the receiver "SHOULD NOT offer a one-click unsubscribe for that message." The RFC also says the receiver "MUST NOT perform a POST on the HTTPS URI without user consent." Providers only send it when a person clicks. ## How do you implement it? ### If you use an email marketing platform Most platforms add both headers for you. Your work is to: 1. Confirm one-click unsubscribe is switched on for your account and every sending domain. 2. Set up custom-domain DKIM so the signature is for your domain and covers both headers. Our [DKIM setup guide](https://iblockspam.com/blog/dkim-setup-microsoft-365-google-workspace) covers the concepts; your platform's documentation has the records. 3. Make sure the platform's suppression list is shared with any other tool that mails the same people, such as your CRM. ### If you send from your own application 1. **Generate a token per recipient and list.** Store it, or sign it with a server secret, so the URL identifies who and what without exposing the email address. 2. **Add both headers** to every marketing message: ``` List-Unsubscribe: , List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` 3. **Build the endpoint.** Accept a POST whose body contains `List-Unsubscribe=One-Click`. RFC 8058 says receivers should send it as `multipart/form-data` and may use `application/x-www-form-urlencoded`, so accept both. Validate the token, suppress the address, and return a 200-class response. No redirect, no cookie check, no confirmation step. 4. **Handle GET separately.** A GET to the same URL can show a confirmation page for people who open the link in a browser. Don't unsubscribe on GET. 5. **Sign with DKIM after adding the headers**, and include both header names in the `h=` tag. 6. **Keep a visible body link** too. Gmail requires one for bulk senders. ## How do you test one-click unsubscribe? Test with a real message, not just your template. 1. **Check the headers.** Send a campaign message to yourself and open the raw source, or paste it into the [Email Header Analyzer](https://iblockspam.com/tools/email-header-analyzer). Confirm both headers are present and exactly spelled. 2. **Check DKIM coverage.** Find the `DKIM-Signature` header and confirm `h=` lists `List-Unsubscribe` and `List-Unsubscribe-Post`. Confirm the receiver reports `dkim=pass` for your domain. Our [Email Deliverability Test](https://iblockspam.com/tools/deliverability-test) shows the DKIM result and which domain signed. 3. **Simulate the provider's POST** against a test subscriber's URL: ``` curl -i -X POST -d "List-Unsubscribe=One-Click" "https://example.com/u/7f3c9a2e?l=news" ``` You want a 200-class status and no `Location` header. Then confirm the subscriber is suppressed in every system that sends to them. 4. **Test the GET path.** Open the same URL in a browser and confirm it doesn't unsubscribe on page load. 5. **Watch Postmaster Tools.** Google's [Compliance status dashboard](https://support.google.com/mail/answer/14668346) checks bulk senders for one-click unsubscribe and for honoring unsubscribes within 48 hours. ## What should happen after someone unsubscribes? The header is only the trigger. The promise to the recipient is that the mail stops, and that depends on what happens behind the endpoint. 1. **Suppress the address everywhere it receives that type of mail.** If your newsletter, CRM and online store all send promotions, one click must reach all three. A recipient who unsubscribes and then gets a promotion from another tool is a likely spam complaint. 2. **Keep the suppression permanent.** Store the address and the date, and check new imports against it, so a later contact upload doesn't quietly re-subscribe the person. 3. **Leave transactional mail alone.** An unsubscribe from marketing shouldn't stop receipts, password resets or security alerts the person still needs. 4. **Meet the deadlines.** Google recommends processing requests within 48 hours and Yahoo requires 2 days for bulk senders. Immediate processing is simplest and avoids sending one more campaign to someone who already left. ## What are common mistakes? - **Only a mailto URI.** Valid under RFC 2369, but it doesn't meet Gmail's one-click requirement. - **The endpoint redirects** to a "You've been unsubscribed" page. RFC 8058 forbids redirects on the POST. - **The endpoint needs a session.** The POST carries no cookies, so a login check fails every time. - **Headers added after signing.** If a later system adds the headers, they're outside the DKIM signature, and receivers shouldn't offer one-click. - **Separate suppression lists.** The marketing platform removes the person, but the CRM keeps mailing them. That leads to spam complaints. See our guide to [spam complaint rates](https://iblockspam.com/blog/spam-complaint-rate-explained). - **Putting it on password resets.** Google excludes transactional messages from the requirement. Adding the header to account mail can let people turn off messages they need. ## Next steps 1. Send yourself a marketing message and confirm both headers and DKIM coverage with the [Email Header Analyzer](https://iblockspam.com/tools/email-header-analyzer). 2. Run the `curl` test above against a test subscriber and confirm the suppression reaches every sending tool. 3. Check your domain's authentication with the [DMARC Checker](https://iblockspam.com/tools/dmarc-checker), since Gmail and Yahoo bulk senders also need DMARC. 4. Register in Google Postmaster Tools and watch the unsubscribe and spam-rate entries. Browse more guides on [running email day to day](https://iblockspam.com/blog/topic/operations). ## Frequently asked questions ### What headers does one-click unsubscribe need? Two. List-Unsubscribe must contain one HTTPS URL, and may also contain a mailto address. List-Unsubscribe-Post must contain exactly List-Unsubscribe=One-Click. RFC 8058 also requires a valid DKIM signature whose h= tag covers both headers, or receivers should not offer one-click for that message. ### Is a mailto List-Unsubscribe header enough for Gmail? No. Google says it will keep supporting mailto links, but they don't meet its one-click unsubscribe requirement. You need an HTTPS URL in List-Unsubscribe plus the List-Unsubscribe-Post header. A mailto link in the message body doesn't meet the requirement either. ### Why does one-click unsubscribe use POST instead of a link? RFC 8058 explains that anti-spam software often fetches URLs in mail headers automatically. If a simple GET request unsubscribed people, those scanners would unsubscribe recipients who never clicked anything. A POST with a fixed body is something scanners don't normally send, so it signals a real request. ### Can the unsubscribe URL redirect to a confirmation page? Not for the one-click POST. RFC 8058 says the sender must not return an HTTPS redirect, and the unsubscribe must complete from the POST alone, without cookies or a login. You can still link a preference page in the message body for people who want to change options. ### How quickly must I process unsubscribe requests? Google recommends fulfilling them within 48 hours, and its Postmaster Tools compliance dashboard checks bulk senders for this. Yahoo requires bulk senders to honor unsubscribes within 2 days. Process them immediately where you can, and share one suppression list across every tool that mails the same people. ## Sources - [RFC 8058: Signaling One-Click Functionality for List Email Headers](https://www.rfc-editor.org/rfc/rfc8058.html) - [RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands](https://www.rfc-editor.org/rfc/rfc2369.html) - [Gmail Help: Email sender guidelines](https://support.google.com/mail/answer/81126) - [Gmail Help: Email sender guidelines FAQ](https://support.google.com/mail/answer/14229414) - [Gmail Help: Postmaster Tools dashboards](https://support.google.com/mail/answer/14668346) - [Yahoo Sender Hub: Sender best practices](https://senders.yahooinc.com/best-practices/) - [Yahoo Sender Hub: FAQs](https://senders.yahooinc.com/faqs/) ## Free tools for this guide - [Bulk Sender Requirements Checker](https://iblockspam.com/tools/bulk-sender-checker): Check your domain against the Gmail, Yahoo and Outlook.com bulk sender rules that DNS can show, with a checklist per provider. - [Email Header Analyzer](https://iblockspam.com/tools/email-header-analyzer): Trace hops and authentication results — runs entirely in your browser. - [Email Deliverability Test](https://iblockspam.com/tools/deliverability-test): Send one email and see its SPF, DKIM and DMARC results, reverse DNS, blocklists, TLS and spam verdict. - [DKIM Checker](https://iblockspam.com/tools/dkim-checker): Validate DKIM keys by selector, including key type and strength. --- Source: iBlockSpam, https://iblockspam.com/blog/one-click-unsubscribe-rfc-8058 (this is a Markdown copy; the HTML page is canonical). Quote with attribution and a link. Site index for AI assistants: https://iblockspam.com/llms.txt