One-Click Unsubscribe: How to Add the List-Unsubscribe Header (RFC 8058)

One-click unsubscribe lets someone leave your mailing list directly from their mail client, without visiting a web page. It is built from two message headers, List-Unsubscribe and List-Unsubscribe-Post, and a small HTTPS endpoint that removes the recipient when it receives a POST request. Gmail and Yahoo require it from bulk senders of marketing mail, and it is one of the cheapest ways to lower spam complaints.

The short version

1. Make a unique URL per recipient. An HTTPS link with a random token that identifies the recipient and the list.
2. Add two headers. List-Unsubscribe: <https://...> and List-Unsubscribe-Post: List-Unsubscribe=One-Click.
3. Handle the POST. Unsubscribe the recipient straight away and return a 2xx status with no redirect.
4. Sign the headers with DKIM. Both headers must be in the signed header list.
5. Test. Check that the control appears, a request works and the address stops receiving mail.

How one-click unsubscribe works

When a message arrives with the two headers, the mailbox provider can show an Unsubscribe control in its own interface, often next to the sender name. If the user taps it, the provider does not open your web page. It sends an HTTPS POST request straight to the URL in your header, with the body List-Unsubscribe=One-Click. Your server removes the recipient and answers with a 2xx status. The user sees a confirmation from their mail app, and no further steps are needed on your side of the experience.

The headers

List-Unsubscribe: <https://mail.example.com/u/8f3a1c9e7b>, <mailto:unsubscribe@example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Which messages need them

• Add them: newsletters, promotions, product announcements, digests and any mail a person subscribed to.
• Leave them off: password resets, receipts, security alerts, shipping notices and other messages the person needs to receive.
• Mixed messages: if a message is mostly promotional, treat it as marketing, even when an action triggered it.

Build the endpoint

The endpoint has one job: accept a POST, find the recipient from the token, suppress them and return a success status. It must not ask the person to log in, solve a captcha or click anything, and it must not redirect, because the mail client sends the request on its own.

PHP (CodeIgniter 4 style)

public function oneClick(string $token)
{
    // The mail client sends a POST with body: List-Unsubscribe=One-Click
    if ($this->request->getMethod() !== 'post') {
        return $this->showConfirmPage($token); // GET shows a page with a button
    }
    $row = $this->subscribers->findByToken($token);
    if ($row) {
        $this->subscribers->suppress($row['id'], 'one-click'); // apply immediately
    }
    // Always answer 200, even for an unknown token, so nothing is leaked
    return $this->response->setStatusCode(200)->setBody('OK');
}

Node.js (Express)

app.post('/u/:token', express.urlencoded({ extended: false }), async (req, res) => {
  const row = await subscribers.findByToken(req.params.token);
  if (row) {
    await subscribers.suppress(row.id, 'one-click'); // apply immediately
  }
  res.status(200).send('OK'); // no redirect, no login
});

app.get('/u/:token', (req, res) => {
  // GET only shows a confirmation page, because scanners open links
  res.render('unsubscribe-confirm', { token: req.params.token });
});

Test the endpoint from the command line

curl -i -X POST -d "List-Unsubscribe=One-Click" https://mail.example.com/u/8f3a1c9e7b

You should see a 200 OK status and no Location header. Then check that the address now appears in your suppression list.

Sign the headers with DKIM

A mailbox provider only trusts the one-click headers when they are covered by a valid DKIM signature. In the signature, the h= tag lists the signed headers, and it must include both:

DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=mail1;
  h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
  bh=...; b=...

If you send through a platform that signs messages for you, make sure your headers are added before signing. If you set the headers in your own application and the platform adds them again, you can end up with duplicates, so check the raw message. For the domain-level setup see authenticate a sending domain.

Suppression and records

• Apply it immediately. The two-day limit is a ceiling, not a target.
• Decide the scope. A request from a newsletter can unsubscribe the person from that list only, or from all marketing mail. State clearly which in your confirmation and preference page.
• Keep a record. Store the address, the list, the time and the source (one-click, link or reply) so you can show that you honoured the request.
• Never re-add. Imports and integrations must check the suppression list so unsubscribed people do not come back.
• Confirm gently. Where the law allows it, a short confirmation page with an option to re-subscribe is fine. Do not make the person work to leave.

Common mistakes

Test checklist

1. Send to Gmail. Send a marketing test to a Gmail address and look for the Unsubscribe control next to the sender name.
2. Read the source. Open Show original. Both headers should appear once, and DKIM should say PASS.
3. Post to the endpoint. Use the curl command above and confirm a 200 response with no redirect.
4. Confirm suppression. The address must be on your suppression list and excluded from the next send.
5. Check the footer. The visible unsubscribe link in the body must work too.
6. Watch the numbers. After launch, watch complaint rate. It should fall as people use the unsubscribe control instead of the spam button.

Further reading and sources

• RFC 8058: Signaling One-Click Functionality for List Email Headers
• RFC 2369: The Use of URLs as Meta-Syntax for Core Mail List Commands
• Google: Email sender guidelines
• Yahoo: Sender best practices
• Related guides: Gmail, Yahoo and Outlook bulk sender requirements and Authenticate a sending domain.