List-Unsubscribe header and one-click unsubscribe
The two RFC 8058 headers, the POST request mailbox providers send, why DKIM must sign them, and how to build an endpoint that honors it in time.
One-click unsubscribe lets a reader leave your list from the mailbox’s own unsubscribe button, without visiting your site. It takes two headers, List-Unsubscribe and List-Unsubscribe-Post, a DKIM signature that covers both, and an HTTPS endpoint that accepts a POST and removes the address without asking anything else. Gmail and Yahoo require it from bulk senders. This post shows the headers, the request, and a working endpoint.
Who requires it
| Provider | Rule | Time to honor |
|---|---|---|
| Gmail | Required for marketing and subscribed mail from senders of 5,000 or more messages a day to personal Gmail accounts. Transactional mail is excluded | 48 hours recommended |
| Yahoo | Required for bulk senders. RFC 8058 POST highly recommended, mailto accepted | 2 days, required |
| Microsoft | Recommends an easy, clearly visible way to opt out for marketing and bulk mail | Not stated |
Both Gmail and Yahoo also require a visible unsubscribe link in the body. The headers do not replace it. The full set of provider rules is in Gmail, Yahoo and Microsoft sender rules: one reference.
The two headers
RFC 8058 defines one-click unsubscribe as two header fields that work together.
List-Unsubscribe: <https://news.example.com/u/8f3a2c9e1b7d>, <mailto:unsubscribe@news.example.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The rules from the RFC:
List-Unsubscribemust contain one HTTPS URI. It may also contain amailto:URI.List-Unsubscribe-Postmust contain exactlyList-Unsubscribe=One-Click. Nothing else is allowed in it.- The URI must identify both the recipient and the list. The request carries no other information, so it cannot ask which list to leave.
- The URI should contain an opaque, hard-to-forge part, and your server should check it. Otherwise anyone can unsubscribe your readers by guessing URLs.
List-Unsubscribe existed long before one-click, in RFC 2369. The new part is the Post header. It tells the mailbox provider that a single POST to the HTTPS URI completes the unsubscribe.
Why the POST matters
Security scanners and link checkers fetch URLs in mail automatically. If a plain GET to your unsubscribe URL removed the address, scanners would unsubscribe people who never clicked. That is why many senders show a confirmation page on GET.
A mailbox provider cannot click through a confirmation page. RFC 8058 solves this by using POST: scanners fetch with GET, and the provider sends a POST only after the user asks to unsubscribe. RFC 8058 says the receiver must not send the POST without user consent.
When a reader clicks the unsubscribe button in their mailbox, the provider sends this to your server:
POST /u/8f3a2c9e1b7d HTTP/1.1
Host: news.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-Click
The body may also arrive as multipart/form-data. Your endpoint should accept both.
DKIM must sign both headers
RFC 8058 requires at least one valid DKIM signature on the message, and the List-Unsubscribe and List-Unsubscribe-Post headers must be listed in that signature’s h= tag. Without it, the RFC says receivers should not offer one-click unsubscribe for the message.
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=news.example.com; s=em1;
h=from:to:subject:date:message-id:list-unsubscribe:list-unsubscribe-post;
bh=...; b=...
The signing has to happen after the headers are added. If you add them in your app and then hand the message to a service that signs it, check that the service includes them in h=. Open a received message in Gmail, choose Show original, and read the h= list in the DKIM-Signature header.
Building the endpoint
If you send through an email platform, it usually builds the URL and handles the POST for you. You need your own endpoint when you send list mail from your own systems, for example product digests generated by your app.
The endpoint must:
- Accept a POST to the exact URI in the header.
- Identify the recipient and list from the URI alone.
- Verify the hard-to-forge token.
- Unsubscribe the address and return a success status.
- Not redirect. RFC 8058 forbids an HTTPS redirect, because redirected POSTs often turn into GETs.
- Not depend on cookies or login. The POST must not include cookies, HTTP authorization or other context.
A GET to the same URL should show a page with a confirm button, for readers who click the link and for scanners that should change nothing.
Here is a minimal Node.js version using Express. The token is an HMAC of the list and subscriber IDs, so the server can check it without a database lookup.
import express from 'express'
import crypto from 'node:crypto'
const app = express()
const SECRET = process.env.UNSUBSCRIBE_SECRET
function sign(listId, subscriberId) {
return crypto
.createHmac('sha256', SECRET)
.update(`${listId}.${subscriberId}`)
.digest('base64url')
}
// Used when you build each message
export function unsubscribeUrl(listId, subscriberId) {
return `https://news.example.com/u/${listId}/${subscriberId}/${sign(listId, subscriberId)}`
}
function valid(listId, subscriberId, token) {
const expected = Buffer.from(sign(listId, subscriberId))
const given = Buffer.from(token)
return expected.length === given.length && crypto.timingSafeEqual(expected, given)
}
// One-click: the mailbox provider POSTs here. The URL carries everything.
app.post('/u/:list/:sub/:token', async (req, res) => {
const { list, sub, token } = req.params
if (!valid(list, sub, token)) return res.sendStatus(404)
await suppress(list, sub) // write to your suppression table. Safe to repeat.
res.sendStatus(200)
})
// A person who clicks the link in the body lands here first.
app.get('/u/:list/:sub/:token', (req, res) => {
const { list, sub, token } = req.params
if (!valid(list, sub, token)) return res.sendStatus(404)
res.send(`<form method="post"><button>Unsubscribe</button></form>`)
})
app.listen(3000)
Notes on the code:
- The handler ignores the request body. The URL identifies the recipient, so the body adds nothing. That also means you do not need a parser for both content types.
suppressmust be idempotent. Providers may retry, and a reader may click twice.- The GET page posts to the same URL, so readers and providers share one code path. RFC 8058 designs the POST target to be the same as the manual unsubscribe page for this reason.
- Return 404 for a bad token, not a page that asks for an email address. One-click has no way to answer a form.
Test it the way a provider will call it:
curl -i -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data "List-Unsubscribe=One-Click" \
"https://news.example.com/u/42/1001/<token>"
You should get HTTP/1.1 200 OK with no Location header, and the address should be suppressed in your database.
Honoring the request in time
Yahoo requires unsubscribes to be honored within 2 days. Gmail recommends 48 hours. In practice, act on the POST at once and make sure every system that sends to the address reads the same suppression list.
The usual failure is not the endpoint. It is a second system. The newsletter tool removes the address, but a CRM sync adds it back the next night, or a separate product email service never hears about it. Check these:
- Every sending system reads one suppression list, or receives unsubscribes by webhook.
- Imports and syncs do not resubscribe suppressed addresses.
- Sends already queued for the address are cancelled or filtered at send time.
- Your unsubscribe page and endpoint stay up. If the endpoint returns an error, the unsubscribe did not happen.
Common mistakes
- An
http://URL inList-Unsubscribe. One-click needs HTTPS. - A tracking redirect in front of the unsubscribe URL. The POST must not be redirected.
- A login or preference page as the only option. It is fine to offer preferences on the GET page, but the POST must unsubscribe on its own.
- Unsigned headers. DKIM must cover both.
- One URL for every recipient. The URI must identify who is leaving and from which list.
Checklist
List-Unsubscribewith one HTTPS URI, optionally amailto:too.List-Unsubscribe-Post: List-Unsubscribe=One-Click.- Both headers in the DKIM signature’s
h=tag, signed after they are added. - A unique URI per recipient and list, with a token your server verifies.
- POST handler that suppresses, returns 200, never redirects and needs no cookies.
- GET page with a confirm button.
- Unsubscribe applied across every sending system within 2 days. Same day is better.
- A visible unsubscribe link in the body as well.
EmailMarketer.io adds both headers to every send automatically. The List-Unsubscribe-Post header needs an HTTPS unsubscribe link, so keep your tracking domain on HTTPS. If your product sends list mail from its own code, the endpoint above covers it. For product mail sent through our API, see transactional email. How the rest of your setup fits the provider rules is on our deliverability page.