Skip to main content

Mailbox providers

Why Isn't the Gmail Unsubscribe Button Showing?

By Tom Sather•Updated October 11, 2026•7 min read

Gmail shows its unsubscribe button only when your mail has correct one-click headers and passes Google's eligibility checks, including its sender requirements.

On this page

Gmail shows the unsubscribe button next to the sender's name only when your message passes Google's automated eligibility checks. To be eligible, the message needs correct one-click unsubscribe headers (List-Unsubscribe with an HTTPS URL, plus List-Unsubscribe-Post, both covered by your DKIM signature) and has to meet Gmail's sender requirements. Even then, Google decides message by message, so a correct setup doesn't guarantee the button every time.

An unsubscribe link in the body of your email doesn't change any of this. Google's FAQ says the eligibility rules apply even when you have your own link in the message.

What the button is and why you want it

When it appears, Gmail puts an "Unsubscribe" link at the top of the message, beside the sender's name. When a recipient clicks it, Gmail sends the unsubscribe request to you on their behalf, using the URL in your List-Unsubscribe header. Some messages show "Go to website" instead, which sends the person to your site to finish the job.

That button is good for you. Someone who wants off your list is going to leave one way or another. If unsubscribing is easy, they unsubscribe. If it isn't, they click "Report spam," and spam reports are what Gmail measures you on. See Gmail's spam rate threshold for why that number matters.

Gmail also has a "Manage subscriptions" view (rolled out from July 2025) that lists a person's subscriptions by sender and lets them unsubscribe in one click. Your headers feed that too.

What Gmail requires

From Google's sender guidelines and FAQ:

  • If you send more than 5,000 messages a day to Gmail accounts, your marketing and subscribed messages must support one-click unsubscribe and include a clearly visible unsubscribe link in the body.
  • One-click unsubscribe means both of these headers:
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://example.com/unsubscribe/abc123>
  • mailto: unsubscribe links are still supported but don't meet the one-click requirement.
  • Transactional messages (receipts, password resets) are excluded from the requirement.
  • Google recommends processing unsubscribes within 48 hours. Yahoo's guidance is to honor them within 2 days.

RFC 8058, the standard behind one-click unsubscribe, adds the technical details: the List-Unsubscribe header must contain one HTTPS URL, the List-Unsubscribe-Post value must be exactly List-Unsubscribe=One-Click, and both headers must be covered by a valid DKIM signature (listed in the signature's h= tag). The POST request your server receives won't carry cookies, and your server must not answer it with a redirect.

Common causes, most likely first

  1. The headers are missing. Some platforms only add List-Unsubscribe to bulk campaigns, not to automated or API-sent mail. Others need it switched on per account or per sending domain.
  2. Only half the headers are there. A List-Unsubscribe header with a mailto: address, or an HTTPS URL without List-Unsubscribe-Post, isn't one-click.
  3. The headers aren't covered by DKIM. If your platform adds the headers after the message is signed, or signs with a header list that leaves them out, they don't meet RFC 8058. This is common with home-built sending setups and relays that modify messages.
  4. You're not meeting Gmail's sender requirements. Failing SPF, DKIM or DMARC alignment, or running a high spam rate, makes the message ineligible. Google ties the button to compliance with the guidelines.
  5. Your reputation or volume pattern doesn't pass the eligibility checks. Google's FAQ says to increase sending volume gradually and to monitor spam reports. It doesn't publish the details of the checks, so if everything technical is right and the button still comes and goes, this is the likely remaining factor.
  6. The message isn't marketing. If Gmail treats it as transactional or one-to-one mail, there may be no reason to show the button.

How to fix it

  1. Open the message in Gmail and look at the raw headers. Use the three-dot menu, then "Show original." Search for List-Unsubscribe. You should see both headers, with an https:// URL in List-Unsubscribe.
  2. Check the DKIM signature covers them. In the same raw view, find the DKIM-Signature header for your domain and read its h= tag. Both List-Unsubscribe and List-Unsubscribe-Post should be in that list. The email header analyzer makes this easier to read.
  3. Confirm authentication passes and aligns. In "Show original," Gmail summarizes SPF, DKIM and DMARC results at the top. All should pass, and DMARC passes only when SPF or DKIM aligns with your From domain. Run the domain through the SPF, DKIM and DMARC checker if anything fails, and see DMARC fail for alignment problems.
  4. Turn on one-click unsubscribe in your sending platform. Many ESPs add RFC 8058 headers automatically or have a setting for it; check your platform's documentation. If you run your own MTA, add the headers before DKIM signing and include them in the signed header list.
  5. Test the unsubscribe URL. Send a POST to it with the body List-Unsubscribe=One-Click and confirm the address is actually removed, without a login, a cookie or a redirect.
  6. Check your spam rate in Postmaster Tools. Google's requirement is to stay below 0.3%, and its best practice is below 0.1%. If you're over, fix that first; the header work won't matter until you do.

How to confirm it's fixed

Send a campaign to a few Gmail addresses you control and open the messages. If the headers and authentication are right, the button usually appears, though Google doesn't promise it for every message. The "Compliance status" dashboard in Google Postmaster Tools also reports one-click unsubscribe as Compliant or Needs work for bulk senders. After that, keep an eye on two numbers over the following weeks: your unsubscribe rate from Gmail recipients (it may tick up, which is fine) and your spam rate in Postmaster Tools (which should hold steady or drop).

How to keep it from coming back

  • Check the raw headers on a sample message whenever you add a new sending platform, change ESPs or move a mail stream to a new subdomain.
  • Keep every service that sends as your domain authenticated and aligned. A forgotten tool sending unauthenticated mail hurts the domain's reputation as a whole.
  • Process unsubscribes promptly and make sure they sync across every platform that mails the same people.
  • Ramp up gradually when launching a new domain or significantly increasing volume. See why email from a new domain goes to spam.

For the bigger picture on Gmail and Yahoo's requirements, see the Gmail and Yahoo bulk sender updates.

When to get help

If your headers are correct and signed, authentication passes, and the button still rarely shows, the issue is likely reputation, and that's harder to read from the outside. Get in touch if you want a second look.

FAQ

Do I need the Gmail unsubscribe button to comply with the bulk sender rules?

You need the one-click headers and a visible unsubscribe link in the body if you send more than 5,000 messages a day to Gmail accounts. Whether Gmail displays its button is Google's decision, but the headers are your responsibility.

Does a mailto unsubscribe header count?

Google still supports mailto: links, but they don't meet its one-click requirement. You need an HTTPS URL in List-Unsubscribe plus the List-Unsubscribe-Post header.

Why does the button show on some messages but not others?

Google evaluates eligibility per message. Different mail streams, platforms or subdomains may have different headers or authentication, and reputation can shift over time. Compare the raw headers of a message that shows it with one that doesn't.

Should transactional emails have List-Unsubscribe?

They're excluded from Google's one-click requirement. Adding it to something like a password reset makes little sense, but for mixed messages such as account newsletters, treat them as marketing and include it.

Sources

Related guides

Still stuck?

Some deliverability problems take an experienced eye to untangle. Tell me what you're seeing and I'll tell you what I'd check first. The first 30-minute call is free.