One-Click Unsubscribe: Gmail, Yahoo, and RFC 8058

In February 2024, Gmail and Yahoo started enforcing a shared set of requirements for bulk email senders: authenticate with SPF, DKIM, and DMARC, keep spam complaint rates low, and support one-click unsubscribe as defined in RFC 8058. These are filtering policies rather than law. Miss them and your mail may land in spam or be rejected during the SMTP conversation, with error codes that point at the sender guidelines.

The requirements are now well documented, but implementations still get the details wrong, most often in the one-click flow. This guide covers what the rules require and where implementations break.

List-Unsubscribe and one-click unsubscribe

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

A compliant marketing message needs two headers, both covered by a valid DKIM signature:

List-Unsubscribe: <https://example.com/unsubscribe/eb7c21a09f3d>
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

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

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 unauthenticated mail during SMTP with errors in the 550 5.7.26 range, so authentication failures surface as bounces rather than silent spam-foldering.

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

The RFC 8058 standard defines the mechanism. A compliant message carries two headers:

List-Unsubscribe: <https://example.com/unsubscribe/eb7c21a09f3d>
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 and Yahoo's sender requirements 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

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.

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.

A short checklist

For a marketing stream sending to Gmail and Yahoo at bulk volume:

1. SPF and DKIM both pass, with the From: domain aligned to at least one of them.
2. DMARC record published at _dmarc.<from-domain>, p=none or stricter.
3. PTR records on sending IPs, TLS on the connection.
4. List-Unsubscribe with an HTTPS URI, plus List-Unsubscribe-Post: List-Unsubscribe=One-Click, both covered by the DKIM signature.
5. A POST endpoint that accepts both standard form encodings, requires no browser state, does not redirect, and suppresses within 48 hours.
6. A visible unsubscribe link in the message body.
7. Spam rate monitored in Postmaster Tools and held below 0.10%.
8. Transactional mail on a separate stream, without unsubscribe headers.

If you are implementing this yourself, verify authentication and alignment first with the email authentication guide. With Samva, attach an unsubscribe group to a marketing send and the message carries the RFC 8058 headers while the platform handles suppression. Use the send API reference to set the unsubscribe group and the deliverability guide to understand bounce and complaint suppression. See the newsletter workflow for the end-to-end setup.

Primary sources

• RFC 8058: Signaling One-Click Functionality for List Email Headers
• Gmail email sender guidelines
• Gmail email sender guidelines FAQ
• Yahoo sender best practices