List-Unsubscribe Header: Gmail and Yahoo Rules

The inbox unsubscribe button is now a sender requirement

A clean newsletter can still lose inbox placement if people have to hunt for the unsubscribe link. Gmail and Yahoo treat easy opt-out as part of sender trust.

For Gmail, the hard line is bulk sending. Google says senders that send more than 5,000 messages per day to Gmail accounts must support one-click unsubscribe for marketing and subscribed messages. Those messages also need a clearly visible unsubscribe link in the body.

Yahoo has the same practical goal. Its Sender Hub says bulk senders should implement a functioning List-Unsubscribe header for marketing and subscribed messages, keep a visible body link, and honor unsubscribe requests within 2 days. Yahoo says the RFC 8058 POST method is highly recommended, and its current guidance also says a mailto: method is acceptable.

If you want one setup that works for both, build RFC 8058 one-click unsubscribe. Add an HTTPS URL in List-Unsubscribe, add List-Unsubscribe-Post: List-Unsubscribe=One-Click, and keep the normal footer link for people who open the message body.

• List-Unsubscribe: <https://example.com/unsubscribe/token>
• List-Unsubscribe-Post: List-Unsubscribe=One-Click
• The HTTPS endpoint accepts POST and removes the address from that list.
• The body still has a clear unsubscribe link.
• Yahoo unsubscribe requests are honored within 2 days. Faster is better.

How one-click unsubscribe should work

One-click means the mailbox can send a POST after the user chooses unsubscribe in the inbox UI. It should not send the person through a login wall or confirmation maze.

RFC 8058 has a few details that matter. The List-Unsubscribe header must contain an HTTPS URI for one-click. It may also contain a non-HTTP URI such as mailto:. The List-Unsubscribe-Post value is fixed: List-Unsubscribe=One-Click.

The message also needs a valid DKIM signature that covers both the List-Unsubscribe and List-Unsubscribe-Post headers. If your email platform adds those headers after DKIM signing, mailbox providers may ignore the one-click signal.

Use an opaque token in the URL instead of a raw email address. The token should identify the recipient and the list. The endpoint should complete the unsubscribe from the POST body alone. Do not require cookies, HTTP auth, or a prior web session. Do not redirect the POST. Do not unsubscribe on a plain GET request, because link scanners and security tools may prefetch URLs.

Who needs it

Bulk marketing and list mail need the header first. Smaller senders should add it too, because a bad unsubscribe flow turns annoyed readers into spam complaints.

For Gmail, the bulk threshold is more than 5,000 messages per day to Gmail accounts. Google lists the rule under requirements for senders at that volume. For Yahoo, the Sender Hub uses bulk-sender requirements and says marketing and subscribed messages need easy unsubscribe.

Transactional mail is different. Receipts, password resets, security alerts, and account notices usually should not include a marketing unsubscribe flow, because the user may need those messages. Mixed messages are the risky case. If a message contains promotional or list content, split it from transactional mail or treat it like promotional mail and include unsubscribe.

The header does not force Gmail, Yahoo, or Outlook to show an unsubscribe button on every message. It gives them a trusted, machine-readable path. Reputation, authentication, complaints, routing, and content still affect whether the message lands in the inbox.

Authentication still has to pass

The unsubscribe header is one part of the Gmail and Yahoo sender rules. SPF, DKIM, and DMARC still carry the sender identity.

Start with SPF. Publish one SPF TXT record for each sending hostname that needs SPF. Include the real services that send with that domain, such as Google Workspace, Microsoft 365, Resend, SendGrid, or your own mail server. RFC 7208 limits SPF evaluation to 10 DNS-querying mechanisms and modifiers. Includes, redirects, a, mx, exists, and ptr can count toward that limit. ip4, ip6, and all do not cause DNS lookups.

Use ~all while you are still finding legitimate senders. Move to -all only after you know the authorized sources are complete and DMARC reports show normal mail passing. SPF -all means fail, but the receiver still decides how to handle the message.

Then fix DKIM. Each sending service should sign mail with a selector under a domain you control, such as s1._domainkey.example.com. Gmail requires DKIM keys of at least 1024 bits for mail to personal Gmail accounts and recommends 2048 bits where supported. For RFC 8058 one-click unsubscribe, the DKIM signature should include the unsubscribe headers in its signed header list.

Then publish DMARC at _dmarc.example.com. A starter record can use p=none with a rua report address so you can see who is sending as your domain. After reports look clean, many domains move to p=quarantine and then p=reject. DMARC passes when SPF or DKIM passes and the authenticated domain aligns with the visible From domain.

• SPF: one SPF record for the checked hostname, real senders included, 10 DNS-lookups or fewer.
• DKIM: every platform signs with your domain, with selectors you can rotate.
• DMARC: bulk Gmail and Yahoo mail needs at least p=none; reports are strongly useful.
• MX: receiving domains need valid MX if you accept replies, bounces, or abuse mail.
• Forward and reverse DNS: sending IPs should have valid PTR records and matching A or AAAA records.
• Blocklists: check them when delivery drops, but treat a listing as a symptom to investigate.

Why mail can still go to spam

Passing the header check does not prove people want the mail. Mailbox providers still score sender history and recipient complaints.

A domain can pass SPF, DKIM, DMARC, and one-click unsubscribe, then still land in spam if recipients report the message, ignore a stale list, or get mail they never asked for. Bought lists, scraped lists, sudden volume spikes, misleading subject lines, and mixed promotional traffic are common causes.

Gmail tells senders to keep the spam rate in Postmaster Tools below 0.10% and avoid ever reaching 0.30% or higher. Yahoo tells bulk senders to keep complaint rates below 0.3%. Microsoft also joined the high-volume sender push: for domains sending over 5,000 messages per day to Outlook.com, Hotmail.com, and Live.com, Microsoft announced SPF, DKIM, and DMARC requirements starting May 5, 2025. That Microsoft rule is about authentication, not the Gmail and Yahoo one-click unsubscribe rule, but the lesson is the same: mailbox providers now expect clean identity and clean list practices.

Use the official sources when the exact wording matters: Google sender guidelines, Yahoo Sender Hub, Microsoft high-volume sender announcement, RFC 8058, RFC 7208, RFC 6376, and RFC 7489.

A clean setup pattern

Use a sending subdomain, sign every message, and keep the unsubscribe endpoint boring.

A common setup is mail.example.com for newsletters and product updates, with SPF, DKIM, and DMARC on that stream. If you send enough volume, separate sales automation, lifecycle mail, and transactional mail. That keeps one weak list from hurting every message your company sends.

After you ship the header, test a real message. View the raw headers in Gmail or Yahoo. Confirm both list-unsubscribe headers are present. Confirm the DKIM signature covers them. Send a test POST to the HTTPS URL and make sure the address is removed from the right list without login, redirect, or a second confirmation.

Then check the domain basics: SPF lookup count, DKIM selectors, DMARC policy, MX, and reverse DNS. A free domain check like InboxRadar can catch DNS drift before a small record change turns into a delivery drop.