# One-click unsubscribe (RFC 8058) explained URL: https://samva.dev/blog/one-click-unsubscribe-rfc-8058 > Set List-Unsubscribe and List-Unsubscribe-Post, then honor one POST, for Gmail and Yahoo bulk senders. Transactional mail such as password resets stays exempt. - Published: 2026-07-07 - Author: [Saatvik Arya](https://samva.dev/authors/saatvik-arya) Gmail and Yahoo require bulk senders to authenticate with [SPF, DKIM, and DMARC](/guides/email-authentication), keep spam complaints below 0.3%, and support one-click unsubscribe: two headers, `List-Unsubscribe` and `List-Unsubscribe-Post`, plus an HTTPS endpoint that removes the recipient from a single POST, within two days. Google counts you as a bulk sender once you send close to 5,000 messages a day to personal Gmail accounts. These rules have applied since February 2024. They are filtering policies rather than law, and miss them and your mail may land in spam or be rejected during the SMTP conversation. Most senders get the authentication part right and the one-click flow wrong. This guide gives the requirements side by side, then shows the `List-Unsubscribe` headers and the endpoint behind them. ## The requirements at a glance [#the-requirements-at-a-glance] Checked against [Google's sender guidelines](https://support.google.com/mail/answer/81126?hl=en), [its FAQ](https://support.google.com/mail/answer/14229414?hl=en), and [Yahoo's sender best practices](https://senders.yahooinc.com/best-practices/) on October 5, 2026. | Requirement | Applies to | Gmail | Yahoo | | --- | --- | --- | --- | | SPF or DKIM passing | Every sender | Required | Required | | SPF and DKIM both passing | Bulk senders | Required | Required | | DMARC, `p=none` or stricter, aligned with SPF or DKIM | Bulk senders | Required | Required | | Forward and reverse DNS (PTR) on sending IPs | Every sender | Required | Required | | TLS on the connection | Every sender | Required | Not listed on its requirements page | | Spam rate | Every sender | Below 0.10%; never reach 0.30% | Below 0.3% | | One-click unsubscribe headers | Bulk senders, marketing and subscribed mail | Required | Required; the POST method is highly recommended | | Honor an unsubscribe | Bulk senders | Within 48 hours | Within 2 days | Transactional mail such as password resets and receipts is exempt from the one-click requirement. ## What the List-Unsubscribe header does [#what-the-list-unsubscribe-header-does] `List-Unsubscribe` tells an email client where a recipient can leave a mailing list. It can advertise a web URL, a `mailto:` address, or both. That header alone does not establish the RFC 8058 one-click flow: the message also needs `List-Unsubscribe-Post`, an HTTPS endpoint that processes the provider's POST, and a DKIM signature covering both headers. The visible unsubscribe link in the email body serves the reader directly. Keep it alongside the headers so recipients can find subscription controls even when their email client does not offer its own unsubscribe button. ## RFC 8058 in one minute [#rfc-8058-in-one-minute] A compliant marketing message needs two headers, both covered by a valid DKIM signature: ``` List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` The HTTPS URI must identify the recipient and list through an opaque, hard-to-forge value. When a mailbox provider sends the POST, the endpoint must complete the unsubscribe without cookies, HTTP authorization, a login, or a confirmation step. It must not redirect the POST. Gmail and Yahoo also require a clearly visible unsubscribe link in the message body. ## Who counts as a bulk sender [#who-counts-as-a-bulk-sender] Google's threshold is close to 5,000 messages or more to personal Gmail accounts within a 24-hour period. Three details matter: - The count aggregates across your primary domain. Mail from `news.example.com` and `mail.example.com` counts toward one total for `example.com`. - Personal accounts means `@gmail.com` and `@googlemail.com` addresses. Google Workspace-hosted domains don't count toward the threshold. - Crossing the line once is enough. Google treats a domain as a bulk sender permanently after it reaches the threshold. Yahoo describes a bulk sender as one sending a significant volume of mail and does not publish Gmail's numeric cutoff. In practice, if you send marketing email at meaningful scale, build to the bulk-sender bar. Senders below Gmail's threshold still need authentication; the one-click requirement is the main bulk-only item. ## The authentication requirements [#the-authentication-requirements] All senders, bulk or not, need: - SPF or DKIM passing on the sending domain - Valid forward and reverse DNS (PTR records) for sending IP addresses - TLS on the SMTP connection Bulk senders need more: - **SPF and DKIM must both pass.** - **A DMARC record on the From: domain**, at minimum `p=none`: ``` _dmarc.example.com. TXT "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com" ``` - **Alignment.** The domain in the visible From: header must match either the SPF domain (the Return-Path) or the DKIM `d=` domain. DMARC evaluates this, and it's the requirement that breaks when you send through a platform using its own envelope domain without a custom DKIM signature for yours. Two adjacent rules round out the authentication set. Sending with an `@gmail.com` address in the From: header through your own infrastructure fails alignment, so bulk senders must use their own domain. And if you forward mail rather than originate it, Gmail expects ARC headers so the original authentication results survive the hop. Gmail rejects mail that fails these checks during SMTP, with `4.7.x` or `5.7.x` errors such as `550 5.7.26`, so authentication failures surface as bounces rather than silent spam-foldering. Our [bounce guide](/blog/email-bounce-back) explains how to read them. ## Spam rate thresholds [#spam-rate-thresholds] Google Postmaster Tools reports your user-reported spam rate, the share of inbox-delivered mail that recipients mark as spam. The published thresholds: - Keep the rate below **0.10%**. - Avoid ever reaching **0.30%**. Above that line, filtering kicks in and can persist for weeks after the rate recovers. Yahoo publishes the same 0.30% ceiling. Because the rate is computed against mail delivered to the inbox, a sender already being spam-foldered sees a distorted picture. Monitor Postmaster Tools directly rather than inferring from engagement drops. The unsubscribe requirement exists partly to protect this number: a recipient who can leave your list in one click has less reason to reach for "report spam" instead. ## How one-click unsubscribe works [#how-one-click-unsubscribe-works] The [RFC 8058 standard](https://www.rfc-editor.org/rfc/rfc8058.html) defines the mechanism. A compliant message carries two headers: ``` List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` Three rules govern them: 1. `List-Unsubscribe` (defined in RFC 2369) may contain a `mailto:` address, an HTTPS URI, or both. RFC 8058 requires at least one HTTPS URI. 2. `List-Unsubscribe-Post` must contain exactly `List-Unsubscribe=One-Click`. 3. The message must carry a valid DKIM signature that covers both headers. When a recipient clicks unsubscribe in the Gmail or Yahoo interface, the provider sends an HTTP POST to your URI: ``` POST /unsubscribe/eb7c21a09f3d HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded List-Unsubscribe=One-Click ``` Your endpoint's contract: - Complete the unsubscribe from this request alone, without a login, a confirmation page, or any further interaction. The recipient's mail client already asked them to confirm. - Identify the recipient and the list from the URI itself. The POST body carries no identifying data, so the URL needs an opaque, hard-to-forge per-recipient token. - Do not depend on cookies, an `Authorization` header, or browser session state. RFC 8058 prohibits that context on the provider's request. - Accept both `multipart/form-data` and `application/x-www-form-urlencoded`. RFC 8058 recommends the former and permits the latter. - Do not redirect the POST. RFC 8058 prohibits HTTPS redirects because clients have historically changed redirected POST requests into GET requests. - Respond with a 2xx status. Serve preference centers and farewell pages at the in-body unsubscribe link, not here. - Process the unsubscribe within 48 hours. Both [Gmail's sender FAQ](https://support.google.com/mail/answer/14229414?hl=en) and [Yahoo's sender requirements](https://senders.yahooinc.com/best-practices/) set that expectation. Suppressing faster is better: a recipient who unsubscribes and still receives the next campaign reaches for the spam button, which counts against your 0.30% ceiling. The POST-with-fixed-body design exists because email links get fetched by machines. Corporate security scanners and client prefetchers follow GET links in messages, and an unsubscribe that fires on GET removes subscribers who clicked nothing. State changes belong behind the POST. One more Gmail requirement sits outside the headers: marketing messages need a clearly visible unsubscribe link in the body. The one-click headers supplement it; both are required. ## Transactional email is exempt [#transactional-email-is-exempt] The one-click requirement covers marketing and subscribed messages. Password resets, receipts, security alerts, and other transactional mail need no unsubscribe mechanism, and adding one creates a trap: recipients click it, you suppress them, and their next password reset goes nowhere. The practical requirement is infrastructure that can tell the streams apart, so the headers attach to campaigns and stay off account mail. We cover the split, and why it also matters for consent and reputation, in [transactional email vs marketing email](/blog/transactional-vs-marketing-email). ## Where implementations break [#where-implementations-break] **A `mailto:` URI with no HTTPS URI.** Satisfies RFC 2369, fails RFC 8058. The one-click flow requires the HTTPS form. **Unsubscribing on GET.** Link scanners will unsubscribe your most security-conscious subscribers, since their corporate mail gateways fetch links in incoming mail. Reserve the state change for POST. **A confirmation step behind the one-click endpoint.** Redirecting the POST to a landing page, or requiring a second click, breaks the contract. The POST must finish the job. **Redirecting the POST.** Even when the final URL processes the unsubscribe, the redirect itself violates RFC 8058. Some clients turn redirected POST requests into GET requests, so serve the unsubscribe response directly from the advertised HTTPS URI. **Assuming one form encoding.** Receivers may send either `multipart/form-data` or `application/x-www-form-urlencoded`. Accept both, or ignore the body after validating the POST path and opaque token. **Depending on browser state.** A mailbox provider's request arrives without cookies, HTTP authorization, or a user session. Put the recipient and list identity in a signed or otherwise hard-to-forge URI token. **Guessable tokens.** The URI is the only carrier of identity, and an enumerable ID like `/unsubscribe/12345` lets anyone unsubscribe your entire list. Use random per-recipient tokens. **Headers added after DKIM signing.** RFC 8058 requires the signature to cover both headers. A relay or edge service that appends `List-Unsubscribe` downstream of your signer produces headers the signature doesn't cover, which fails the requirement even though both headers are present. **Stale endpoints.** Recipients unsubscribe from old messages. Keep tokens valid well past the send date; an endpoint that returns 404 a month later drops legitimate unsubscribes and earns spam reports instead. **Missing DMARC alignment.** A correct one-click implementation earns nothing if the message fails authentication. Providers evaluate the sender guidelines as a package. If you are implementing this yourself, verify authentication and alignment first with the [email authentication guide](/guides/email-authentication). With Samva, every campaign email carries the RFC 8058 headers for its topic (the one the campaign names), and a transactional send carries them when you attach a topic, while the platform handles suppression. Use the [send API reference](/docs/api-reference/messages/send) to set the topic and the [deliverability guide](/docs/channels/email/deliverability) to understand bounce and complaint suppression. See the [newsletter workflow](/solutions/newsletters) for the end-to-end setup. ## Primary sources [#primary-sources] - [RFC 8058: Signaling One-Click Functionality for List Email Headers](https://www.rfc-editor.org/rfc/rfc8058.html) - [Gmail email sender guidelines](https://support.google.com/mail/answer/81126?hl=en) - [Gmail email sender guidelines FAQ](https://support.google.com/mail/answer/14229414?hl=en) - [Yahoo sender best practices](https://senders.yahooinc.com/best-practices/)