One-Click Unsubscribe: RFC 8058 and the Gmail and Yahoo Sender Requirements

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 lands in spam or gets rejected during the SMTP conversation, with error codes that point at the sender guidelines.

Two years in, the requirements are stable and 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.

Who counts as a bulk sender

Google's threshold: 5,000 or more messages 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 applies a similar threshold and describes it less precisely. In practice, if you send marketing email at meaningful scale, build to the bulk sender bar. Senders below the 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

RFC 8058 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 per-recipient token.
• Respond with a 2xx status. Serve preference centers and farewell pages at the in-body unsubscribe link, not here.
• Process the unsubscribe within two days, per Gmail's guideline. 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.

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 completes the unsubscribe with no further interaction and suppresses within two days.
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.

Samva is a modern email API for product teams. The docs cover domain verification and sending. Start sending.