One-click unsubscribe is the mechanism defined in RFC 8058 that allows mailbox providers to process unsubscribe requests via a single HTTP POST, without requiring the recipient to visit a confirmation page. It's implemented via the List-Unsubscribe-Post header working alongside List-Unsubscribe. Gmail and Yahoo require it for all senders sending 5,000+ messages per day. It is one of the key [email deliverability](/email-deliverability/email-deliverability-guide) requirements.
What Is One-Click Unsubscribe?
One-Click Unsubscribe: No Friction, No Excuses
One-click unsubscribe removes every barrier between a recipient wanting to stop your emails and actually stopping them. One click. No confirmation page. No "are you sure?" No preference center detour.
Gmail displays this as the "Unsubscribe" link next to your sender name. When a user clicks it, Gmail sends a POST request to your endpoint and the recipient is unsubscribed instantly.
Required Headers
List-Unsubscribe: <https://example.com/unsub?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Both headers must be present. Without List-Unsubscribe-Post, Gmail falls back to opening the URL in a browser — which doesn't meet the one-click requirement.
How the POST Works
When the recipient clicks unsubscribe in Gmail or Yahoo:
- Provider sends
POST https://example.com/unsub?token=abc123 - Request body:
List-Unsubscribe=One-Click - Your server suppresses the recipient
- Your server returns
HTTP 200
The entire flow happens server-to-server. The recipient never sees your website.
Implementation Requirements
Your POST endpoint must:
- Accept POST — not GET, not redirect to GET
- Process immediately — Gmail expects suppression within 2 days, but process instantly if possible
- Return 200 — any other status code means the unsubscribe failed
- Work without authentication — no login required, no CAPTCHA
- Be idempotent — multiple POSTs for the same address shouldn't cause errors
ESP Support
Most ESPs handle this automatically:
| ESP | One-Click Support |
|---|---|
| Mailgun | Automatic |
| SendGrid | Automatic |
| Postmark | Automatic |
| Amazon SES | Manual implementation |
| Self-hosted | Manual implementation |
If you're on Amazon SES or self-hosting, you need to build the POST endpoint yourself and inject both headers into outgoing emails. Make sure your SPF, DKIM, and DMARC are also configured correctly alongside these headers.
Practitioner note: The most common one-click unsubscribe failure I see is endpoints that return a 302 redirect to a confirmation page instead of a 200. The redirect worked before RFC 8058 enforcement, but Gmail now expects a direct 200 response. Check your endpoint with
curl -X POSTto verify.
Practitioner note: Some senders try to use the one-click POST as a trigger for a "sorry to see you go" email. Don't. The recipient just told you they want to stop receiving email. Sending another email in response is the opposite of respecting that request.
For the full header specification, see List-Unsubscribe. If you need help implementing one-click unsubscribe on a self-hosted setup, schedule a consultation — I'll build the endpoint and configure your MTA headers.
Sources
- RFC 8058: Signaling One-Click Functionality for List Email Headers
- RFC 2369: List-Unsubscribe
- Google: One-Click Unsubscribe Requirement
- Yahoo: Sender Requirements
v1.0 · April 2026
Frequently Asked Questions
How does one-click unsubscribe work technically?
The mailbox provider sends an HTTP POST request to the URL in your List-Unsubscribe header with the body 'List-Unsubscribe=One-Click'. Your server processes the unsubscribe and returns a 200 status. No redirect, no confirmation page, no user interaction beyond the initial click.
Is one-click unsubscribe the same as List-Unsubscribe?
No. List-Unsubscribe provides the unsubscribe URL. One-click unsubscribe (List-Unsubscribe-Post) tells the provider to use that URL via POST without a confirmation step. You need both headers for compliance.
What if my unsubscribe page requires confirmation?
Your one-click POST endpoint must process the unsubscribe immediately without confirmation. You can still have a separate web-based unsubscribe page with preferences, but the POST endpoint must work independently for one-click compliance.
Do I need one-click unsubscribe for transactional emails?
No. One-click unsubscribe is required for marketing and promotional emails. Transactional emails (order confirmations, password resets) are exempt. But if you mix marketing content into transactional emails, providers may classify them as marketing.
Want this handled for you?
Free 30-minute strategy call. Walk away with a plan either way.