One-Click Unsubscribe: How to Add List-Unsubscribe Headers

One-click unsubscribe lets a recipient opt out from the mail client's own unsubscribe button, with no confirmation page. It is built from two email headers, List-Unsubscribe and List-Unsubscribe-Post, defined in RFC 8058. Gmail and Yahoo require it for marketing mail from bulk senders.

What does the header setup look like?

A compliant message includes headers like these:

List-Unsubscribe: <https://example.com/unsubscribe/abc123>, <mailto:[email protected]>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The https link must accept an HTTP POST request and unsubscribe the recipient without asking for a login or further clicks. RFC 8058 also requires the message to carry a valid DKIM signature that covers both headers.

Who needs to do this?

Google requires one-click unsubscribe for marketing and subscribed messages from bulk senders, meaning those sending about 5,000 or more a day to Gmail. Yahoo has matching rules. Most sending platforms add the headers for you, so check settings before building anything yourself. See the full requirements.

How do you implement and test it?

1. Check whether your email platform enables one-click unsubscribe by default. If it does, confirm it in the message source.
2. If you build your own sending, add both headers, generate a unique unsubscribe URL per recipient and process POST requests on it.
3. Also keep a visible unsubscribe link in the message body.
4. Send a test to Gmail and look for the Unsubscribe link next to the sender name. Open Show original to see the headers.
5. Process unsubscribes quickly. Google asks senders to honor them within two days.

Why is this good for deliverability?

When unsubscribing is easy, people use it instead of hitting the spam button. Complaints are weighted much more heavily than unsubscribes, so a smooth opt-out protects your reputation. Pair it with careful list hygiene and monitor your complaint rate in Postmaster Tools.

What are common mistakes with one-click unsubscribe?

• Pointing the URL at a page that needs a login or a second confirmation click.
• Adding the headers but not signing them with DKIM.
• Using the same unsubscribe URL for every recipient, so the system cannot tell who opted out.
• Taking weeks to apply opt-outs, so people keep receiving mail they asked to stop.

Fixing these removes a frequent source of complaints and keeps you inside the Gmail and Yahoo rules.

What about transactional messages?

The requirement targets marketing mail. Receipts and password resets do not need one-click unsubscribe, and should be sent separately so they never depend on marketing opt-out status. More in deliverability best practices.

Frequently asked questions

Do I still need an unsubscribe link in the body?

Yes. Google requires a visible link in the message body in addition to the one-click header.

What is List-Unsubscribe-Post?

A header with the value List-Unsubscribe=One-Click that tells mail clients the HTTPS URL accepts a one-click POST request.

Do I need a DKIM signature for this?

Yes. The standard requires DKIM signing that covers the List-Unsubscribe headers.

How fast must unsubscribes be processed?

Google's guidelines say within two days.