One-Click Unsubscribe: What Gmail and Yahoo Require

Introduction

One-click unsubscribe is a requirement from Gmail and Yahoo for bulk senders of marketing and promotional mail. Each message must carry two headers defined in RFC 8058, List-Unsubscribe with an HTTPS URL and List-Unsubscribe-Post, and both must be covered by a valid DKIM signature. Unsubscribe requests must be honoured within two days.

The DKIM part is where this touches DMARC, and where most implementations quietly fail: if the signature does not cover the headers, the mailbox provider will not show the unsubscribe button. This article covers what the requirement says, which messages it applies to, what the headers look like and how an MSP checks each client's sending platforms. For the wider rule set, see Google, Yahoo and Microsoft sender requirements compared, and for the protocol background, the DMARC guide.

Key takeaways

• Gmail and Yahoo require one-click unsubscribe on marketing and promotional mail from bulk senders. Transactional mail is not included.
• RFC 8058 needs two headers: List-Unsubscribe with one HTTPS URL, and List-Unsubscribe-Post: List-Unsubscribe=One-Click.
• Both headers must be included in a valid DKIM signature. Without it, receivers should not offer one-click unsubscribe.
• The unsubscribe endpoint must accept a POST without cookies or login, and must not answer with a redirect.
• Honour requests within 48 hours (Google) or two days (Yahoo).

What do Gmail and Yahoo require for unsubscribe?

Both require one-click unsubscribe, as defined in RFC 8058, on marketing and subscribed mail from bulk senders, and both expect requests to be processed quickly. Microsoft asks for a functional, easy-to-find unsubscribe link but does not mandate RFC 8058.

Google also states that a mailto: link or a link to a landing or preferences page does not meet the requirement on its own. Any additional unsubscribe link in the message body does not have to be one-click and can lead to a preferences page.

Which messages need one-click unsubscribe?

Marketing and promotional messages from bulk senders. Google says plainly that the requirement applies only to marketing and promotional mail, and that transactional messages such as password resets, reservation confirmations and form submission confirmations are excluded.

In practice, sort every stream a client sends into one of three groups:

• Needs one-click: newsletters, offers, product announcements, event invitations, re-engagement campaigns.
• Does not need it: password resets, order and shipping confirmations, invoices, security alerts, replies to support tickets.
• Grey zone: account digests, "you might like" recommendations, onboarding sequences with promotional content. Treat these as marketing; if a recipient could reasonably want to stop them, give them the button.

Google counts the bulk threshold (about 5,000 messages a day to personal Gmail accounts) across the primary domain, including its subdomains. A client that sends marketing from a subdomain does not escape the threshold that way.

What do the RFC 8058 headers look like?

Two headers, both in the message header section:

List-Unsubscribe: <https://unsubscribe.example.com/u/7f3a9c2e41d8>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=mkt2026; h=from:to:subject:date:list-unsubscribe:list-unsubscribe-post; ...

RFC 8058, Section 3.1, sets the rules for each header:

When the recipient clicks the provider's unsubscribe button, the provider sends an HTTPS POST to that URL with List-Unsubscribe=One-Click in the body. The endpoint must process it without asking the user anything further.

Why does DKIM have to sign the unsubscribe headers?

Because RFC 8058 makes it a condition. Section 4 says the sender must apply at least one valid DKIM signature, and the List-Unsubscribe and List-Unsubscribe-Post headers must be covered by it, meaning they appear in the signature's h= tag. If they are not, the receiver "SHOULD NOT offer a one-click unsubscribe".

That makes DKIM setup on the marketing platform doubly important. The same signature that should align with the From domain for DMARC also has to cover the unsubscribe headers. Three failure patterns are common:

1. The platform signs with its own domain, not the client's. The headers are signed, but DKIM does not align with the From domain, so DMARC relies on SPF alone. Turn on custom DKIM with the client's domain.
2. The headers are added after signing. A relay, gateway or footer tool inserts List-Unsubscribe after the DKIM signature was applied, so the headers are not in h=.
3. An intermediary rewrites the headers. Any change to a signed header breaks the signature, which breaks both one-click and DKIM-based DMARC alignment. See why DMARC fails when SPF passes for how that shows up.

What must the unsubscribe endpoint do?

Accept the POST, unsubscribe the recipient and return success, with no extra steps. RFC 8058 sets three rules for the sender's side:

• The POST must work without cookies, HTTP authorisation or any other context, so the URL itself has to identify the recipient and list.
• The server must not respond with an HTTPS redirect, because redirected POSTs often fail or turn into GETs.
• The sender must run the infrastructure to handle these requests, rather than relying on someone reading a mailbox.

The endpoint should also verify the opaque identifier in the URL, so nobody can unsubscribe other people by guessing addresses.

How do you check a client's setup?

Send a real campaign message to a test mailbox you control and read the raw headers. How to read email headers shows where to look. For each marketing platform the client uses, check:

1. Both headers are present on marketing messages, with one HTTPS URL in List-Unsubscribe.
2. List-Unsubscribe-Post contains only List-Unsubscribe=One-Click.
3. The DKIM signature passes, uses the client's domain in d=, and lists both headers in h=.
4. Look for the "Unsubscribe" option that Gmail's web interface can show next to the sender name. Gmail decides when to display it, so its absence is not proof of a fault, but it is a prompt to recheck the headers and DKIM coverage.
5. An unsubscribe actually takes effect within two days, including in the CRM or any second platform that mails the same list.

Most established email service providers add the headers automatically once custom DKIM is enabled. The gaps usually appear in self-built systems, CRMs that send marketing mail without a marketing module, and relays that modify messages. DMARC and Mailchimp and DMARC and SendGrid cover two common platforms.

How does this fit into an MSP's DMARC work?

It belongs in the same per-sender review. When discovery finds a marketing platform, the questions are the same ones DMARC already asks (does it sign with the client's domain, does that signature align?) plus one more: does the signature cover the unsubscribe headers? Add a column for it to the sender inventory described in DMARC client discovery.

The unsubscribe processing itself is a marketing system task, not a DNS task. The MSP's job is to confirm the headers and signature are right and to tell the client who owns the deadline for honouring requests.

FAQ

Is one-click unsubscribe required for transactional email?

No. Google says the requirement applies only to marketing and promotional messages, and gives password resets, reservation confirmations and form submission confirmations as examples of mail that is excluded.

Is a mailto link enough?

No. Google requires one HTTPS URL in the List-Unsubscribe header. A mailto: address can be listed alongside it, but on its own it does not meet the requirement.

Does the unsubscribe link in the email body count?

Not as the one-click mechanism. The requirement is met by the headers. Google says any additional link in the body does not have to be one-click and can lead to a preferences page.

Why does Gmail not show the unsubscribe button for my mail?

The usual technical causes are missing headers, a DKIM signature that does not cover them, or a signature that fails. Gmail also decides itself when to display the option. Check the raw headers of a received message for both headers and for list-unsubscribe in the DKIM h= tag.

Does one-click unsubscribe affect DMARC?

Not directly; DMARC does not check the unsubscribe headers. But both depend on the same DKIM signature, so a platform that signs with the client's own domain and covers the headers satisfies both at once.

Final thoughts

One-click unsubscribe looks like a marketing feature, but it rests on the same foundation as DMARC: a valid DKIM signature from the client's own domain. Check both in one pass for every marketing platform, and the unsubscribe requirement becomes one more line in the sender inventory rather than a separate project.