Where you saw it: Gmail showing the unsubscribe control and nothing happening, complaints continuing from people who say they unsubscribed, or your endpoint logs showing POST requests returning errors.
Why it happens
- The endpoint only accepts GET. Mailbox providers send a POST, and a GET-only route returns an error nobody sees.
- The endpoint requires a session or a login, which a provider's automated request cannot supply.
- It returns a confirmation page instead of completing the action, so the request succeeds and the person stays subscribed.
- The unsubscribe token expired or was single-use and already consumed by a link scanner.
- The suppression is queued for a batch job rather than applied immediately.
The fix, in order
Send a POST at your own endpoint
Run the exact request a provider sends, with the List-Unsubscribe=One-Click body, and confirm you get a 200 and the address is suppressed.
Accept POST without authentication
The request arrives from Google or Yahoo, not from the subscriber's browser. There is no session and there cannot be one.
Complete the action on the request itself
No confirmation step, no preference center. The specification means what it says, and an intermediate page is a failure.
Make tokens durable enough to survive scanners
Security products follow links in mail. A single-use token can be spent by a scanner before the person clicks, which makes their real click fail.
Suppress synchronously
Write the suppression before returning the response. A queued job that runs hourly risks sending again to someone who just opted out.
curl -X POST -d 'List-Unsubscribe=One-Click' https://example.com/u/abc123Exactly what a mailbox provider sends. A 200 and a suppressed address is the pass.
How to know it worked
The short version
- A manual POST to your endpoint returns 200 and suppresses the address immediately.
- Endpoint logs show provider POSTs succeeding rather than erroring.
- Unsubscribes from the inbox control appear in your platform within seconds.
Questions people ask
Why does the provider POST instead of GET?
To prevent link scanners and prefetchers from unsubscribing people by accident. A POST is a deliberate action, which is why your endpoint must accept one.
Can I show a confirmation page?
Not as part of one-click. The action must complete on the request. You can show a page to someone who clicks the footer link instead.
How quickly must the unsubscribe take effect?
Within 48 hours under Google's guidelines, and immediately in practice. Sending again to someone who just unsubscribed is the fastest way to earn a complaint.