Do I need one-click unsubscribe if I only send 500 emails a month?

Not as a requirement. Gmail ties it to senders of more than 5,000 messages a day to Gmail accounts, and the count covers your primary domain and its subdomains together. It is still worth doing at any size, because the alternative exit your readers have is the spam button, and Gmail calculates the user-reported spam rate daily against a 0.3% ceiling.

Is a mailto: List-Unsubscribe header enough?

It depends on the provider. Yahoo's sender best practices accept the mailto method while recommending the RFC 8058 POST method. Gmail's sender guidelines FAQ states that mailto and plain URL unsubscribe links do not meet its one-click requirement, so for Gmail you need an HTTPS URI in List-Unsubscribe plus the List-Unsubscribe-Post header.

I added both headers and the Gmail unsubscribe button still does not appear. Why?

The usual cause is the DKIM signature. RFC 8058 requires both header fields to be inside the signed header set, listed in the h= tag, and says a receiver that finds no such signature should not offer one-click for the message. Gmail's help also notes that the button next to the sender name appears only for messages that pass Google's automated eligibility checks, even when the sender has added an unsubscribe link of their own.

List-Unsubscribe header: one-click setup for Gmail

Say a twenty-person firm sends one newsletter a month. It goes out from the same domain that carries invoices and support, there is an unsubscribe link in small grey type at the bottom, and open rates have been sliding for a year. Then someone forwards a screenshot: in Gmail, right next to the sender name, other newsletters show a tidy unsubscribe button and theirs does not. Two months later the whole send lands in spam for a good part of the list.

Those two facts are connected. That button is not a Gmail courtesy and it is not the link in your footer. It comes from two header fields carried by the message itself, and when they are missing, or present but unsigned, the only quick exit left to a tired reader is the spam button. A spam report is the most expensive signal in deliverability. An unsubscribe costs you one address. This is the setup we put in for clients, in the order we do it, and what we check before changing anything.

What that button actually reads

One-click unsubscribe is RFC 8058, a standards-track specification published in January 2017. It works through two header fields:

List-Unsubscribe: <https://mail.example.com/u/9f2c1b7a4e8d>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe is much older and can carry a mailto: address, an HTTPS URL, or both. On its own it is not one-click. The second field is the signal, and RFC 8058 is exact about it: the header must contain the single key and value pair List-Unsubscribe=One-Click, nothing else. Gmail's sender guidelines FAQ says the same thing from the other side, that other kinds of unsubscribe, mailto links and plain URL links, do not meet its one-click requirement.

One detail in the specification saves you a bad week later: the URI should carry an opaque identifier or another component that is hard to forge. Anyone who can read the header can call the endpoint, so a URL shaped like ?email=someone@example.com lets a stranger unsubscribe your customers by editing a query string. Generate a random token per subscriber per list and resolve it on your side.

Who has to do this, and who should anyway

Gmail's sender guidelines, checked on 15 October 2026, tie the requirement to volume: senders of more than 5,000 messages a day to Gmail accounts must support one-click unsubscribe in their marketing and subscribed messages, and must also include a clearly visible unsubscribe link in the body. The FAQ adds the part people miss, that the 5,000 are counted across the primary domain, subdomains included, so three small streams from three subdomains add up to one bulk sender. The requirement covers marketing and subscribed mail, not transactional mail.

Yahoo's sender best practices ask for a working List-Unsubscribe header that supports one-click on marketing and subscribed messages, call the RFC 8058 POST method highly recommended and accept the mailto method, want the visible link in the body as well, and ask that requests be processed within two days. Microsoft's requirements for high-volume senders into Outlook.com consumer mailboxes sit on authentication, SPF, DKIM and DMARC for domains over 5,000 messages a day, and list a functional unsubscribe link among its additional hygiene recommendations rather than as an enforced rule.

Most of the businesses we work with are nowhere near 5,000 a day. The threshold decides whether this is mandatory, not whether it is worth doing. Gmail's own ceiling for user-reported spam is 0.3% and it recommends staying under 0.1%, and that rate is calculated daily. If 2,000 of your addresses are Gmail, six spam reports in a single day puts you at 0.3% for that day. Six readers who could not find the exit is not a large failure of judgement. It is a missing header.

The headers only work if DKIM covers them

This is the failure we find most often, and it is invisible from the sending side. RFC 8058 requires the message to carry at least one valid DKIM signature, and both List-Unsubscribe and List-Unsubscribe-Post must be inside the signed set, listed in the signature's h= tag. A receiver that does not find such a signature should not offer one-click for that message. So the platform adds the headers, the marketing team sees them in the raw source, and the button still never appears.

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=example.com; s=selector1;
 h=from:to:subject:date:list-unsubscribe:list-unsubscribe-post;
 bh=...; b=...

Reading the signed header list in a real message is the only way to confirm it. Send one copy of the campaign to a mailbox you control, open the original, and check three things: both fields present, both named in h=, and the signing domain aligned with the domain in your From address so DMARC passes on the DKIM side.

What the endpoint has to do

When a reader consents, the mail provider sends an HTTPS POST to your URI with List-Unsubscribe=One-Click as the body. RFC 8058 says that content should be sent as multipart/form-data and may be sent as application/x-www-form-urlencoded, so accept both. The rest of the specification is a list of things your endpoint must not need:

No redirect. The sender must not answer with an HTTPS redirect, because redirected POST actions have historically been unreliable. A marketing site that bounces every path to a locale prefix, or http to https, breaks one-click without a single error anyone sees.
No cookies, no authorization. The POST must not include cookies, HTTP authorization or any other context. Your endpoint cannot ask who is logged in. The opaque token has to be enough on its own.
No confirmation step. One POST ends the subscription. A page that answers with "click here to confirm" is not one-click, and the reader never sees that page anyway.
No second guessing. The provider only POSTs after the person consents, so treat every request as a real decision, return a 200, and make it idempotent so a repeated POST is not an error.

Then act inside the window. Gmail asks that unsubscribe requests be processed within 48 hours, Yahoo within two days. An endpoint that files the request in a queue a person empties on Fridays will miss that, and the reader who clicked on Monday and got Thursday's campaign reaches for the spam button instead.

What we check on a client's sending before changing anything

Which streams are really subscription mail. Receipts, password resets and booking confirmations are not, and Gmail's subscription guidelines ask that subscription and non-subscription messages be sent from different addresses. Sorting the streams first usually simplifies everything after it.
Who controls the headers. One-click is sender-side configuration, platform by platform. In a real sending platform it is a setting plus a verified sending domain. Mail sent straight from a mailbox, a plugin or a script has no unsubscribe machinery at all, and that is the honest signal that the newsletter has outgrown where it lives.
List identity. Gmail's subscription guidelines say each subscription can be identified by a human-readable List-id: header or by a unique From address per list. This matters as soon as there is more than one list: someone leaving the monthly newsletter should not also lose their receipts.
The body link stays. Gmail and Yahoo both still want a clearly visible unsubscribe link in the message. One-click does not replace it, and the body link is the one that may lead to a preference page where people choose what to keep.
How the list was built. Gmail's subscription guidance points to double opt-in before sending subscription messages. One-click on a list nobody asked for only makes the exit faster.

The mistakes we find most

In the audits we run, the same handful comes up again and again. A mailto: address alone in List-Unsubscribe, which Yahoo accepts and which does not meet Gmail's one-click requirement. Both headers present and neither named in the DKIM h= tag. An unsubscribe URL that sits behind a login, so the POST cannot work. A redirect in front of the endpoint. The recipient's address in the URL in plain text. The headers added to transactional mail, which turns a password reset into a support ticket. And the unsubscribe that is technically perfect and lands in a spreadsheet nobody reads until the end of the month.

What we watch after the change

Postmaster Tools is where this shows up. Watch the user-reported spam rate day by day against the 0.3% ceiling, with 0.1% as the number to aim at, and expect unsubscribes to rise at first. That rise is the mechanism working: people who were going to leave are leaving through the door instead of the alarm. Watch the inbox placement on the same domain over the following month, and read the Postmaster Tools dashboards together rather than one at a time.

Be honest about what this does not fix. One-click unsubscribe lowers the complaint rate you generate from here on. It does not repair a reputation already earned, it does not authenticate anything, and it does not clean a list bought three years ago. If mail is already landing in spam, the authentication and volume work comes first and this comes with it, because complaint rate is the slowest of the signals to recover.

How Guanacos Tech helps

We do this as part of deliverability work for small and mid-sized teams across North America and Latin America: separate the subscription streams from the mail your business runs on, get both headers emitted and signed, review the endpoint against the specification, confirm it on a real message, then watch the complaint rate with you for the month after. How we work fits on one page. If you would rather have the headers verified than researched, we offer email deliverability consulting for small business, and half an hour with one of your campaigns open is enough to say whether the button will appear and what it takes to get it there.

One-click unsubscribe: the two headers Gmail reads, and the endpoint behind them