One-click unsubscribe lets someone leave your list from the inbox's own Unsubscribe button, with no login or form. You add two headers from RFC 8058: List-Unsubscribe with an HTTPS link, and List-Unsubscribe-Post set to List-Unsubscribe=One-Click. Gmail and Yahoo require it on marketing mail from bulk senders.
| Source | Unsubscribe rule |
|---|---|
| Gmail | One-click unsubscribe on marketing mail for senders of 5,000+ a day; visible link in the body; handle requests within 48 hours (recommended) |
| Yahoo | Functioning list-unsubscribe header with one-click (RFC 8058); honor unsubscribes within 2 days |
| CAN-SPAM (US) | Clear way to opt out; honor it within 10 business days; mechanism works for at least 30 days after sending |
| Transactional mail | Gmail: one-click not required for transactional messages |
Updated
Most email services add these headers for you once you turn on list management, so check there first. If you send from your own app or server, the builder below writes the two header lines, and the examples show the small endpoint that has to answer the inbox's request.
List-Unsubscribe: <https://example.com/unsub/8f3a2c91d0>, <mailto:[email protected]?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickReady to paste. Remember to include both headers in your DKIM signature.
A minimal handler in standard JavaScript (the Request and Response objects used by most modern hosts). It removes on POST and asks for confirmation on GET.
Replace removeSubscriber with your own database call. The token is the hard-to-guess part of the address.
export async function handle(request, removeSubscriber) {
const token = new URL(request.url).pathname.split("/").pop();
if (request.method === "POST") {
const form = await request.formData();
if (form.get("List-Unsubscribe") === "One-Click") {
await removeSubscriber(token);
return new Response("Unsubscribed", { status: 200 });
}
return new Response("Bad request", { status: 400 });
}
// GET: a person or a link scanner. Show a button that POSTs.
return new Response(
'<form method="post"><input type="hidden" name="List-Unsubscribe" value="One-Click">' +
'<button>Confirm unsubscribe</button></form>',
{ headers: { "content-type": "text/html" } }
);
}The mail app reads your List-Unsubscribe header and sends an HTTPS POST to that address. The request body is the value of List-Unsubscribe-Post, encoded as a form, so your endpoint receives List-Unsubscribe=One-Click.
Your server finds the subscriber from the token in the address and removes them. Nothing else is sent: no cookies, no login, no extra page.
The FTC's compliance guide lists the core duties for commercial email: truthful From, To and routing details, a subject line that matches the content, a clear note that the message is an ad, a valid physical postal address, and an easy opt-out.
Each email that breaks the rules can cost up to $53,088 according to the FTC guide as of October 2026, so a working unsubscribe is cheap insurance.
Gmail's requirement applies to senders of about 5,000 or more messages a day to Gmail accounts. Smaller senders still need a working opt-out under laws like CAN-SPAM, and adding the headers is good practice anyway.
Gmail says one-click unsubscribe is required only for marketing and promotional messages, and transactional messages are excluded. The FTC's guide also treats purely transactional email as mostly exempt from CAN-SPAM.
Not for one-click. RFC 8058 needs at least one HTTPS address in the header. A mailto address can sit next to it as a fallback for older mail apps.
As of October 2026, Gmail recommends within 48 hours and Yahoo asks for within 2 days. The US CAN-SPAM Act sets a legal maximum of 10 business days.
No. The FTC guide says the Act does not require prior consent, but it does require honest headers and subject lines, identifying the message as an ad, your physical postal address, and an opt-out you honor.
Related: Double opt-in, Google Postmaster Tools, SPF, DKIM and DMARC, How to create an email newsletter, Email marketing best practices.
Start for free or see all free tools. We.Inc is free to start, with no card needed. AI building is on paid plans from $20 a month.
We.Inc is an AI-powered website builder you can resell under your own brand. Launch a branded client dashboard, bill on Stripe Connect, and deliver AI-generated websites in minutes. White-label plans start at $99 a month for 25 client sites, with a 7-day free trial and no per-site fees.