One-Click Unsubscribe: RFC 8058 Implementation Guide

What One-Click Unsubscribe Is

RFC 8058 defines a mechanism for recipients to unsubscribe from email lists with a single action — no forms, no confirmation pages, no login required.

When implemented correctly, Gmail displays an "Unsubscribe" link at the top of the email. The recipient clicks it. A POST request is sent to your server. The recipient is unsubscribed. Done.

The Required Headers

List-Unsubscribe: <https://yourdomain.com/unsubscribe?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Both headers are required. List-Unsubscribe alone (without List-Unsubscribe-Post) doesn't satisfy the one-click requirement — it's the older mailto-based unsubscribe.

How It Works

1. Email includes both headers
2. Gmail/Yahoo detects the headers and shows "Unsubscribe" button
3. Recipient clicks "Unsubscribe"
4. Gmail sends HTTP POST to your List-Unsubscribe URL
5. Your server processes the POST and removes the recipient
6. Recipient is unsubscribed — no confirmation page needed

The POST request body contains: List-Unsubscribe=One-Click

ESP Implementation Status

ESP	Auto-implements?	Notes
Klaviyo	Yes	Enabled by default on all marketing emails
Mailchimp	Yes	Enabled by default
ActiveCampaign	Yes	Enabled by default
SendGrid	Yes	Added to marketing emails via API/SMTP
Mailgun	Partially	Must configure headers in API or template
Brevo	Yes	Enabled by default
MailerLite	Yes	Enabled by default
Postmark	Yes	On Broadcast (marketing) streams
Kit	Yes	Enabled by default
GoHighLevel (LC Email)	Yes	Via Mailgun integration
GoHighLevel (custom SMTP)	No	Must add headers yourself

If Using Custom SMTP Without ESP Headers

When sending via custom SMTP (GoHighLevel with Mailgun/SendGrid, self-hosted, or application email), you must add the headers yourself:

In your email sending code:

headers['List-Unsubscribe'] = '<https://yourdomain.com/unsubscribe?token=UNIQUE_TOKEN>'
headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click'

Your unsubscribe endpoint must:

1. Accept POST requests
2. Read the List-Unsubscribe=One-Click body
3. Process the unsubscribe (remove from list or suppress)
4. Return HTTP 200 OK

How to Verify

1. Send a marketing email to your personal Gmail
2. Open the email
3. Click three dots → Show Original
4. Search for List-Unsubscribe in the headers
5. Verify both List-Unsubscribe: and List-Unsubscribe-Post: are present

If only List-Unsubscribe: exists (without List-Unsubscribe-Post:), the one-click mechanism isn't active — just the legacy mailto-based unsubscribe.

Common Issues

Headers present but Gmail doesn't show Unsubscribe button:

• Gmail caches header evaluation. It may take several sends for the button to appear.
• Your sender must have some established reputation — very new senders may not show the button immediately.

Custom SMTP with GoHighLevel missing headers:

• GHL doesn't add List-Unsubscribe headers when using custom SMTP (unlike LC Email). You need your SMTP provider or sending script to add them.
• Mailgun API: include headers in the API call
• SendGrid API: use the mail_settings.unsubscribe object or custom headers

Unsubscribe URL doesn't work with POST:

• The URL must accept POST requests, not just GET. Gmail sends a POST, not a browser redirect. If your endpoint only handles GET, the one-click fails.

Practitioner note: Most deliverability issues I investigate don't come down to one-click unsubscribe — the major ESPs handle it automatically. But for GoHighLevel agencies using custom SMTP, this is a real gap. GHL doesn't add the headers for custom SMTP. If you're sending marketing campaigns through GHL + Mailgun without adding these headers yourself, you're non-compliant with Gmail/Yahoo requirements.

Practitioner note: An easy way to make unsubscribe work better: honor unsubscribes instantly (not "within 10 business days"). The faster you process it, the lower your complaint rate. Someone who successfully unsubscribes doesn't report you as spam. Someone who tries to unsubscribe and still gets email does.

If you need one-click unsubscribe implemented for your custom SMTP or GoHighLevel setup, schedule a consultation.

Sources

• RFC 8058: Signaling One-Click Functionality for List Email Headers
• Google: One-Click Unsubscribe Requirement
• Yahoo: Sender Best Practices

---

v1.0 · March 2026