One-click unsubscribe: what it is and how to set it up

Someone opens your newsletter. They don’t want it anymore. They look for the unsubscribe link, but it’s tiny, grey and hidden at the very bottom.

So they do the easy thing. They click “Report spam”.

You didn’t just lose one subscriber. You got a complaint, and complaints are one of the strongest signals Gmail and Yahoo use to decide where your next email lands.

One-click unsubscribe fixes this. It puts a clear “Unsubscribe” option right next to your sender name, inside Gmail or Yahoo. For bulk marketing mail, it is no longer optional. This guide explains what it is, who needs it, how to set it up, and how to prove it really works.

What is one-click unsubscribe?

One-click unsubscribe is a way for the mailbox, such as Gmail or Yahoo, to send the unsubscribe request to you on behalf of the reader. The reader clicks “Unsubscribe” in their mailbox. The mailbox tells your system. Your system stops sending. The reader never has to open your website.

There are two kinds of unsubscribe option, and they live in different places:

The List-Unsubscribe header is old. It was defined in RFC 2369 back in 1998. The “one-click” part was added in 2017 by RFC 8058, which introduced a second header, List-Unsubscribe-Post. RFC 8058’s goal is simple: let people unsubscribe “in a familiar environment and without leaving” their mailbox.

Why easy unsubscribing matters

People don’t always see a difference between “unsubscribe” and “report spam”. RFC 8058 says this openly: if unsubscribing is too hard, people report the mail as junk until it stops arriving.

Google makes the same link. Its sender guidelines FAQ says one-click unsubscribe helps you keep a low spam rate, which improves delivery. Gmail asks senders to keep their spam rate below 0.1%, and never let it reach 0.3%.

One-click vs footer links, preference centers and mailto

Many senders think they already “have” one-click unsubscribe. Often they have something else. Here is how the options compare for Gmail’s rule:

So for bulk marketing mail you need both: the one-click headers, and a clear link in the body. Gmail’s email sender guidelines say marketing and subscribed messages “must support one-click unsubscribe, and include a clearly visible unsubscribe link in the message body.”

Who needs one-click unsubscribe?

Am I a “bulk sender” in Gmail’s eyes?

• The number: about 5,000 or more messages to personal Gmail accounts in 24 hours.
• Subdomains count together. 2,500 emails from example.com plus 2,500 from news.example.com make you a bulk sender.
• It’s permanent. Reach it once, and you stay a bulk sender, even if your volume drops later.
• Personal accounts only. The rules cover @gmail.com and @googlemail.com, not Google Workspace business accounts.

Yahoo doesn’t publish any number. Its sender best practices simply say bulk senders must have a working list-unsubscribe header. Microsoft lists “functional unsubscribe links” as a recommendation in its requirements for high-volume senders.

What about transactional emails?

Password resets, order confirmations and booking confirmations don’t need one-click unsubscribe. Yahoo’s sender FAQ and Gmail both say so. But be honest about what “transactional” means. Gmail notes that recipients, not Google, decide what kind of message they received. A “receipt” full of promotions is a marketing email in the reader’s eyes.

Mailbox rules are not the same as the law

Gmail and Yahoo set their own rules. Laws are separate, and usually less strict on timing:

The simple rule: aim for immediate. Then you meet every deadline at once.

How one-click unsubscribe works

It happens in three simple steps:

1. You add two headers to each marketing email.
2. The reader clicks “Unsubscribe” in Gmail or Yahoo. The mailbox sends a small, automatic request (an HTTPS POST) to the link in your header.
3. Your system receives it and turns off that person’s subscription for that list.

Here are the two headers. This is what Gmail and RFC 8058 show as the example:

List-Unsubscribe: <https://example.com/unsubscribe/opaquepart>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe: <https://example.com/unsubscribe/opaquepart>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Why DKIM matters here

RFC 8058 says both headers must be covered by your DKIM signature. If they aren’t, the mailbox “SHOULD NOT” offer one-click unsubscribe. This stops anyone from adding a fake unsubscribe header to your mail. If DKIM is new to you, read SPF, DKIM and DMARC explained first.

How to set it up with an email platform

This is the easy path, and the right one for most marketers. Follow these six steps:

1. Find your real sending path. Do you send campaigns from the platform’s editor, through its API, or both?
2. Check the platform’s help pages for “List-Unsubscribe” or “one-click unsubscribe”.
3. Find out if it’s automatic, or if you must turn on a setting.
4. Decide what “unsubscribe” removes: one list or topic, or all marketing email.
5. Set up the footer link in your email template.
6. Send a real test campaign to your own Gmail and Yahoo addresses, and check the result (section 09).

What popular platforms do

Still choosing a platform? Add “one-click unsubscribe is automatic” to your must-haves. Our guide on how to choose an email service provider includes it in a ready-made comparison checklist.

How to set it up with your own sending system

This part is for developers, or for anyone who sends through their own server or code. If your email platform handles it, you can skip to section 08.

What should happen after someone unsubscribes?

A working button is only half the job. The other half is making sure the person really stops getting email, everywhere, and stays that way.

• Record it:the status, the date and time, and where it came from (header, footer or preference page)
• Stop future sendsfor that list or topic, starting now
• Check scheduled campaigns and queues, so a message already waiting doesn’t go out
• Sync every system:your email platform, CRM, automations and any spreadsheets
• Protect against re-imports.An old CSV file must never turn the person back on. Keep a master “do not send” file (section 12 shows how)
• Keep essential messages running.A password reset or order confirmation should still arrive

One list, or everything?

Gmail says one-click unsubscribe removes the person only from the mailing list tied to that message. You control the scope. But Gmail’s newer Manage subscriptions page works differently: when someone unsubscribes there, Gmail unsubscribes them from all active mailing lists related to that sender. Be ready for both.

How to test your one-click unsubscribe setup

Don’t assume it works. Test it from start to finish, the way a real reader would use it.

1. Send a real campaign through your normal sending path to a test list with your own Gmail and Yahoo addresses.
2. Open the raw message. In Gmail, open the email, click the three dots, then Show original.
3. Find both headers: List-Unsubscribe with an https:// link, and List-Unsubscribe-Post: List-Unsubscribe=One-Click.
4. Check DKIM. It should say PASS, and the h= part of the DKIM signature should list both list-unsubscribe and list-unsubscribe-post.
5. Trigger the unsubscribe for your test contact (from the mailbox button, or with the command below).
6. Check the status changed in your email platform.
7. Send the next test campaign and confirm the test contact is skipped.
8. Test the footer link separately, with a second test contact.
9. Re-import an old file that contains the test contact, and confirm they stay unsubscribed. If you filter files with MailVexa first, the test contact should appear as Invalid with the reason “ExcludedEmail”.

curl -i -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "List-Unsubscribe=One-Click" \
  "https://example.com/unsubscribe/opaquepart"

curl -i -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data "List-Unsubscribe=One-Click" \
  "https://example.com/unsubscribe/opaquepart"

Common problems and how to fix them

Myths about one-click unsubscribe

Unsubscribing and email verification solve different problems

These two things are often confused. They answer two different questions:

An address can be perfectly valid and still be off-limits. Someone who unsubscribed last month still has a working mailbox. Email validation will say “Valid”. That must never bring them back onto your list.

This is where the two work together. Before every import, you check two things: who may receive email, and which of those addresses actually work.

Where unsubscribed people sneak back in

A one-click unsubscribe works perfectly inside your email platform. The danger is everything outside it. These are the most common back doors:

Your email platform can only protect what it knows. So the safest place to stop these people is before the file reaches your platform. That takes two simple habits.

Habit 1: Keep one master “do not send” file

Keep it outside your email platform, so it survives every platform change. Put these addresses in it:

• Unsubscribes, from every platform, list and audience you have ever used
• Spam complaints
• Hard bounces from past campaigns
• People who asked to stop by replying, by phone or in person

Three rules keep it reliable:

Habit 2: Run every new file through MailVexa before import

MetaLogic MailVexa is email verification software that runs on your own Windows or Mac computer. It does your exclusion and your email list validation in one pass:

1. Import the new file (CSV, TXT, XLSX or XLS) and confirm which column holds the email addresses.
2. On the cleanup page, keep duplicate removal on. MailVexa also trims spaces and lowercases addresses, so [email protected] and [email protected] count as one contact.
3. Open “Exclude specific emails” and load your do-not-send.txt file, or paste the list.
4. Read the “Excluded Emails” counter in the List Cleanup Summary. It tells you how many people from your “do not send” file were hiding in this new file.
5. Verify the rest. Excluded addresses are skipped: MailVexa doesn’t check them at all.
6. Review the results. Every excluded address appears under Invalid with the reason “ExcludedEmail”, so you can see exactly who was blocked and why.
7. Export only Valid for your campaign. Keep Risky and Unknown in separate files. If your platform has import limits, split the export into smaller files by rows per file.

Why exclude before you verify?

For the full cleaning routine, see how to clean your email list before sending a campaign, and for every screen of the app, how to use MailVexa.

One-click unsubscribe checklist

• Every marketing email hasList-Unsubscribewith an HTTPS link
• Every marketing email hasList-Unsubscribe-Post: List-Unsubscribe=One-Click
• DKIM passes and covers both headers
• A clearly visible unsubscribe link is in the email body
• The one-click request needs no login, form or confirmation page, and never redirects
• Unsubscribes are applied right away, and never later than 48 hours
• Every sending path (editor, API, automations) has been checked
• Scheduled campaigns and queues respect new unsubscribes
• I keep one master “do not send” file, and only ever add to it
• Every new file is filtered against it before import
• I tested the whole flow, including the next campaign after unsubscribing

Common questions

Is a footer unsubscribe link enough?

Not for bulk marketing mail to Gmail and Yahoo. You need the one-click headers and a visible footer link. They work together.

Can I use a mailto link instead?

Yahoo accepts mailto. Gmail doesn’t count it as one-click. Use an HTTPS link, and add mailto as a second option if you like.

Do transactional emails need one-click unsubscribe?

No. Gmail and Yahoo require it only for marketing and subscribed messages. Password resets and order confirmations are excluded.

Why doesn’t Gmail show the unsubscribe button?

Gmail shows it only for messages that pass its automated eligibility checks. Check your headers and DKIM. If they’re correct, a missing button is not a setup error.

Does one-click unsubscribe remove someone from every list?

Not by default. It removes them from the list tied to that message. But Gmail’s Manage subscriptions page unsubscribes people from all of a sender’s lists.

Can I offer “fewer emails” instead of a full unsubscribe?

Yes, on a preference page linked from your footer. It can’t replace the one-click headers, and a full unsubscribe must still be available.

How do I stop unsubscribed contacts from being imported again?

Keep a permanent “do not send” list, and filter every new file against it before import. An exclude list in your email verification software, such as MailVexa, makes this automatic: excluded people are skipped and never reach your Valid export.

Sources

Standards

• RFC 8058: Signaling One-Click Functionality for List Email Headers. Headers, HTTPS POST, token, no redirect, DKIM coverage.
• RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands. Origin of the List-Unsubscribe header.

Mailbox providers

• Gmail email sender guidelines. One-click unsubscribe plus visible body link, spam rate.
• Gmail sender guidelines FAQ. Bulk sender definition, 48 hours, mailto, preference pages, transactional mail, enforcement, button eligibility.
• Gmail: Manage subscriptions. Unsubscribing from all of a sender’s lists.
• Yahoo Sender Best Practices. RFC 8058 highly recommended, mailto acceptable, 2 days.
• Yahoo Sender FAQ. Footer link alone not enough, transactional mail excluded.
• Microsoft: Outlook’s requirements for high-volume senders. Functional unsubscribe links recommended.

Laws

• FTC: CAN-SPAM Act compliance guide. 10 business days, 30 days.
• CRTC: CASL frequently asked questions. 10 business days.
• GDPR, Regulation (EU) 2016/679. Article 7(3), withdrawing consent.

Email platforms

• Mailchimp: About unsubscribes
• Klaviyo: List-Unsubscribe header
• MailerLite: List-unsubscribe header and one-click unsubscribe
• ActiveCampaign: How List-Unsubscribe helps email deliverability
• Brevo: FAQs about list-unsubscribe and list-help headers
• Twilio SendGrid: List-Unsubscribe
• Mailgun: Unsubscribe handling links
• Amazon SES: Subscription management
• Postmark: How to include a List-Unsubscribe header

Product

• MetaLogic MailVexa. Desktop email verification software for Windows and macOS.

We build MetaLogic MailVexa, so weigh our description of it accordingly. We have no commercial relationship with any email platform mentioned in this guide. Provider rules and platform features were checked in October 2026 and change often, so confirm them on each provider’s own site. This guide is not legal advice.