The two standards in one table
List-Unsubscribe is old; the one-click part was added much later. Mailbox providers now look for both.
| RFC 2369 (1998) | RFC 8058 (2017) | |
|---|---|---|
| Header | List-Unsubscribe | List-Unsubscribe-Post |
| Value | One or more URIs, each in angle brackets, separated by commas | Always exactly List-Unsubscribe=One-Click |
| Allowed URIs | mailto: and http(s): (a client uses the first one it supports, reading from the left) | Needs at least one https: URI in List-Unsubscribe; mailto alone cannot be one-click |
| What the mail provider does | Shows an unsubscribe option that opens the link or composes an email | Sends an HTTPS POST to your URI in the background, with no page for the recipient to fill in |
| Authentication | Not required by the RFC | The message needs a valid DKIM signature that covers both headers |
| Your endpoint | A page or mailbox that removes the person | Must act on the POST alone, without cookies, a login or a redirect |
Building your headers
Enter the HTTPS endpoint
This is the address on your server (or your sending service's) that unsubscribes whoever the link belongs to. It must start with https:// and be reachable from the public internet.
Add the per-recipient placeholder
Type whatever your sending tool replaces for each recipient, for example
{{token}}. If the URL does not contain it, an Add placeholder to URL button appears and appends it as au=parameter. The placeholder is kept unencoded in the mailto subject too, so your tool can still swap it.Optionally add a mailto fallback
A mailbox that removes anyone who writes to it, plus an optional subject. Mail clients that do not support one-click use this instead.
Choose one-click and folding
Leave One-click ticked to add List-Unsubscribe-Post. Fold long lines splits the header after a comma so no line passes 78 characters, the length RFC 5322 recommends.
Fix anything flagged, then copy
Notes marked Fix will break the header or stop one-click from working; Check notes are worth a look. Copy the header block and the DKIM h= list into your mail setup.
A print studio's newsletter, with a token and a mailto fallback
The inputs were an endpoint of https://mail.brightsideprint.example/unsubscribe?u={{token}}, a mailto of unsubscribe@brightsideprint.example with the subject Unsubscribe {{token}}, one-click on and folding on. The tool reported no problems and produced the block below.
Notice that the space in the subject became %20 while {{token}} stayed as it was. Underneath is the request a mailbox provider sends to the endpoint: the tool fills the placeholder with a sample token so you can see the full path.
HTTPS URL: https://mail.brightsideprint.example/unsubscribe?u={{token}}
Placeholder: {{token}}
Mailto: unsubscribe@brightsideprint.example
Subject: Unsubscribe {{token}}List-Unsubscribe: <https://mail.brightsideprint.example/unsubscribe?u={{token}}>,
<mailto:unsubscribe@brightsideprint.example?subject=Unsubscribe%20{{token}}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
POST /unsubscribe?u=7Hq2xN HTTP/1.1
Host: mail.brightsideprint.example
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
List-Unsubscribe=One-ClickWhat your endpoint has to do
The POST arrives from the mailbox provider's servers, not from the recipient's browser. It carries no cookies and no login, so the URL itself must identify who is leaving and from which list. That is why a token in the path or query matters: an endpoint at a bare /unsubscribe has no way to know who clicked.
Answer the POST directly with a success status. RFC 8058 tells senders not to answer with a redirect, because redirected POST requests have a long history of being dropped or turned into GET requests. Do the removal on the POST itself; do not ask for a confirmation click, since nobody is there to make it.
A plain GET to the same URL is a different matter. Recipients who open the link by hand, and some security scanners that follow links in mail, will send a GET. A sensible pattern is to show a confirmation page on GET and unsubscribe on POST, so a scanner cannot remove people by accident.
Terms on this page
- One-click unsubscribe
- An unsubscribe the mailbox provider performs for the recipient with one HTTPS POST, defined in RFC 8058. The recipient never visits your site.
- DKIM h= tag
- The list of headers a DKIM signature covers. For one-click to be trusted, list-unsubscribe and list-unsubscribe-post must be in it. Your mail server or sending service writes the signature; you configure which headers it signs.
- Header folding
- Splitting a long header over several lines by starting each continuation line with a space. Receivers join the lines back together before reading the value.
- Per-recipient token
- A random value, unique to each recipient and list, that your server maps back to an address. It keeps the email address itself out of the URL.
Questions people ask
What is the List-Unsubscribe-Post header?
It is the header defined in RFC 8058 that turns a List-Unsubscribe link into a one-click unsubscribe. Its value is always List-Unsubscribe=One-Click. When a recipient clicks unsubscribe, the mailbox provider sends that text as an HTTPS POST to the URI in your List-Unsubscribe header, and your server removes the address.
Does Gmail require one-click unsubscribe?
Google's email sender guidelines ask anyone sending more than 5,000 messages a day to Gmail accounts to support one-click unsubscribe in marketing and promotional mail, and to honour requests within two days. Yahoo publishes similar requirements. Below that volume it is still good practice, and the headers cost nothing to add.
Can I use only a mailto address?
Yes for RFC 2369, no for one-click. A mailto-only List-Unsubscribe header is valid, and many clients will offer it. One-click needs an HTTPS URI, so with mailto alone leave List-Unsubscribe-Post out; the generator flags this as an error if one-click is ticked without an HTTPS address.
Which DKIM headers must be signed for one-click unsubscribe?
RFC 8058 requires a valid DKIM signature that covers both List-Unsubscribe and List-Unsubscribe-Post. Without that, a provider cannot be sure the headers were not added by someone else, and may ignore them. The generator shows an h= list including both, alongside the usual From, To, Subject, Date and Message-ID.
Why does my unsubscribe URL need a token?
The one-click POST carries no cookies, no login and no details about the reader, only the fixed text List-Unsubscribe=One-Click. The URL is therefore the only thing that tells your server who to remove. Use a random per-recipient value rather than the email address itself, so the address is not exposed in logs.
Does Map Extract's bulk email sender add these headers?
Its documented safeguards are in the message itself: every message must contain opt-out wording, suppression is checked before sending, and withdrawals are honoured. The capability notes do not describe it writing List-Unsubscribe headers, so view the original headers of a test message sent through your own route to see what is present.
Where your data goes
The headers are assembled by JavaScript on this page. Your endpoint address, mailbox and placeholder are not sent anywhere, and the tool never contacts your unsubscribe URL to test it; the POST shown is an illustration of what a provider would send.
Checked against the tool on