How to Implement One-Click Unsubscribe (RFC 8058)

If you send marketing email in bulk, this guide shows how to implement one-click unsubscribe the way RFC 8058 defines it: two message headers, both covered by your DKIM signature, and a small HTTPS endpoint that accepts an unauthenticated POST.

It is a sender task, not a mailbox setting. Google, Yahoo and Apple require it for marketing mail, and most first attempts fail on the same few details: a cookie on the endpoint, an HTTP redirect, or a header left out of the DKIM signature. We will fix those before they cost you a delivery.

The short answer#

One-click unsubscribe needs four things to line up. Miss any one and mailbox providers treat the offer as absent.

End to end, it works like this: the provider reads your headers, the recipient taps Unsubscribe, and the provider posts to your endpoint. No login, no landing page, no confirmation click. Your server does the removal and returns a success.

• A List-Unsubscribe header whose value includes one HTTPS URI. A mailto: address may sit alongside it as a fallback.
• A List-Unsubscribe-Post header with the exact value List-Unsubscribe=One-Click.
• Both headers covered by a valid DKIM signature and listed in the signature's h= tag.
• An HTTPS endpoint that accepts an unauthenticated POST with the body List-Unsubscribe=One-Click, removes the address, and does not redirect.

What the headers look like#

The two headers travel on every marketing message. The provider reads them, and when the recipient taps Unsubscribe it sends the POST on their behalf.

The HTTPS URI carries a per-recipient token, shown here as 8f2c1a. That token is how your endpoint knows who to remove without asking anyone to log in. The mailto: address is optional and only serves older clients that do not support one-click.

Before you start#

A few things need to be true before the headers do anything.

• You already pass DKIM. One-click rides on DKIM; without a valid signature covering the two headers, the mechanism is void.
• Your unsubscribe URL is reachable over HTTPS. RFC 8058 requires an HTTPS URI. Plain HTTP is not accepted.
• You can identify the subscriber from the URL alone. The spec needs enough data in the link to unsubscribe automatically, with no session and no cookie.
• The mail is marketing or subscribed mail, not transactional.

Implement it step by step#

Six steps, in order. The first three go on the message; the last three build and lock down the endpoint.

1. 1

   Add the List-Unsubscribe header

   Set List-Unsubscribe to one HTTPS URI in angle brackets. The URI must carry a token that identifies the subscriber, so no login is needed. You may add a mailto: address after it as a fallback for older clients.

2. 2

   Add the List-Unsubscribe-Post header

   Set it to exactly List-Unsubscribe=One-Click. RFC 8058 requires this single key/value pair and nothing else. Its presence is what tells the provider your HTTPS URI will accept a one-click POST.

3. 3

   Cover both headers with DKIM

   List both List-Unsubscribe and List-Unsubscribe-Post in the h= tag of your DKIM-Signature. RFC 8058 requires them to be covered by a valid signature. If they are not signed, providers ignore the one-click offer even when the headers are present.

4. 4

   Stand up the POST endpoint

   At the unsubscribe URL, accept an HTTPS POST. The request body will be List-Unsubscribe=One-Click, form-encoded (multipart/form-data is also allowed). Read the subscriber token from the URL, not from the body.

5. 5

   Keep the endpoint stateless

   Require no cookies, no session and no authorization. RFC 8058 says the POST must not include cookies, HTTP authorization, or any other context. And do not answer with an HTTP redirect: the spec forbids it, because redirected POSTs have historically been unreliable.

6. 6

   Unsubscribe, then return success

   Remove the address from the list and return a plain HTTP success such as 200 OK. The RFC does not mandate a status code, but the request is a machine action, so do the work server-side and answer quickly with no page to render.

One trap: guard the GET path#

There is a single mistake that breaks otherwise-correct implementations, and it can quietly unsubscribe real people. Automated systems follow links.

Platform differences#

The mechanism is one standard, but the mailbox providers scope it differently. Requirements change, so confirm current terms on each provider's postmaster page before you rely on this table (checked August 2026).

What to do when it doesn't work#

Most first attempts fail on the same handful of details. Match the symptom to the likely cause, then apply the one-line fix.

How to test it#

To confirm the whole path, send a test to a Gmail or Yahoo mailbox. Check that an Unsubscribe control shows next to your sender name, that clicking it removes you, and that it lands you on nothing because the provider handled it in the background.

If the control never appears, the cause is almost always the DKIM h= tag rather than the headers themselves. Re-sign a test message with both header names in h= and try again.

A faster way: where AI Emaily fits#

Everything above is sender-side work. You are the one running the campaigns, and RFC 8058 is how you let people leave them. AI Emaily sits on the other side of that exchange.

We are a mail client, not an email service provider. We do not send your campaigns and we do not generate your List-Unsubscribe headers; your sending platform does that. What we do is the receiving job: triage the flood those campaigns create. Our cold-email filter and spam protection keep unsolicited outreach and low-value bulk mail out of the way, so the marketing you did not opt into does not bury the mail that matters. We build AI Emaily. If your problem is the inbox rather than the send, that is the part we work on.