List-Unsubscribe Header Generator

What is the List-Unsubscribe header?

The List-Unsubscribe header (RFC 2369) is a message header that tells the recipient's mailbox provider how to unsubscribe. Its value is one or two entries in angle brackets — an https URL, a mailto address, or both — separated by a comma, for example <mailto:unsubscribe@example.com>, <https://example.com/unsub?id=123>.

When it's present and the message authenticates, Gmail, Yahoo, Outlook and Apple Mail render a native unsubscribe button by the sender name. That gives recipients a trusted way to opt out and keeps them from hitting the spam button — which is what actually damages your sending reputation.

One-click unsubscribe (RFC 8058) and the 2024 Google & Yahoo rules

One-click unsubscribe adds a second header, List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058), alongside an https URL. The mailbox provider then unsubscribes the recipient with a single HTTP POST to your endpoint — no landing page or extra click. A mailto value alone can't be one-click, so the https method is required for it.

Since February 2024, Google and Yahoo require bulk senders (about 5,000+ messages a day to their users) to support one-click List-Unsubscribe and to honour opt-outs within two days, alongside SPF, DKIM, DMARC and a spam-complaint rate under 0.3%. Meeting these rules is now a baseline for landing in the inbox rather than the spam folder.

How to add these headers

Most email service providers add compliant List-Unsubscribe and List-Unsubscribe-Post headers automatically when you send a marketing campaign — you usually just confirm the feature is on. If you send through raw SMTP or a transactional API, you add the two header lines yourself and stand up an endpoint that accepts the POST and unsubscribes the recipient.

Use the generator above to build the exact header lines from your unsubscribe URL and mailto address, then copy them into your ESP settings or your message headers. Whichever route you take, keep a visible unsubscribe link in the body as well — the headers complement it, they don't replace it.

How to implement the one-click unsubscribe POST endpoint

When a recipient clicks the unsubscribe button, Gmail or Yahoo sends an HTTP POST to the https URL in your List-Unsubscribe header — Content-Type application/x-www-form-urlencoded, body List-Unsubscribe=One-Click (RFC 8058). It is a server-to-server request from the mailbox provider, so the recipient is never redirected to your site and never sees a page. Your endpoint has to recognise that body, unsubscribe the recipient, and return a 2xx status. Do the heavy work asynchronously if you need to, but acknowledge quickly and make the handler idempotent, because the same POST can arrive more than once.

The POST body is a fixed string with no recipient in it, so the recipient has to be encoded in the URL itself. Give every message a unique link like https://example.com/unsub?id=8f3c9a and look the subscriber up from that token. Use a random or HMAC-signed token rather than the raw email address: the URL is visible in the headers, and a guessable one lets anyone unsubscribe your recipients or harvest addresses. The endpoint must not require a login, cookie, JavaScript or confirmation step.

In practice the same URL usually handles two things: a GET, when a person clicks the unsubscribe link in the message body, which can show a normal confirmation page; and a POST, the one-click request, which must unsubscribe immediately with no further interaction. Keep the two paths separate in your handler so the one-click POST never depends on the confirmation UI.

How to test your List-Unsubscribe header in Gmail

Send a test message to a Gmail address, open it, and use the three-dot menu then Show original. In the raw message, confirm that both List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click are present and that SPF, DKIM and DMARC all show PASS — Gmail suppresses the unsubscribe control when authentication fails. You can also paste the raw text into Emailchaser's free email header analyzer to read the headers and auth results without hunting through the source.

When everything is valid, Gmail shows an Unsubscribe link next to the sender name at the top of the message. Don't panic if it doesn't appear on the first send from a brand-new domain: Gmail surfaces the control more reliably once a sender has some reputation and volume, even when the header itself is perfect. The header is still doing its job — provider unsubscribe buttons and the two-day rule work off it regardless of whether the top-of-message link renders for you.

To check the POST handler without waiting on Gmail, simulate the provider's request from a terminal: curl -X POST -d 'List-Unsubscribe=One-Click' 'https://example.com/unsub?id=123'. You should get a 2xx response and see that recipient marked unsubscribed. If curl works but Gmail's button doesn't, the problem is almost always authentication or reputation, not your endpoint.

mailto vs HTTPS unsubscribe: when to use each

A mailto value unsubscribes by emailing an address you monitor, such as <mailto:unsubscribe@example.com>. It works in essentially every client, and Apple Mail uses it to power its own one-tap Unsubscribe, but it can never be one-click in the RFC 8058 sense because it can't carry the List-Unsubscribe-Post header. Choosing mailto also means building automation that reads that inbox and removes the recipient within two days, and keeping the mailbox itself deliverable.

An https value plus List-Unsubscribe-Post is the only combination that satisfies Google and Yahoo one-click. You don't have to choose, though — list both and let each provider pick the method it supports, for example List-Unsubscribe: <mailto:unsubscribe@example.com>, <https://example.com/unsub?id=123>. Gmail and Yahoo take the https one-click path, while older or niche clients fall back to the mailto. If you only implement one, make it https so you stay compliant with the bulk-sender rules.

The full Google and Yahoo bulk-sender checklist

One-click unsubscribe is one line on a longer checklist that applies once you send around 5,000 messages a day to Gmail or Yahoo personal accounts (counted per From-header domain — cross it once and you're treated as a bulk sender). Alongside the one-click List-Unsubscribe and a visible in-body unsubscribe link, both providers require you to authenticate with SPF and DKIM, publish a DMARC record, and align the From domain with SPF or DKIM so DMARC passes. You also can't send bulk mail from an @gmail.com From address.

The rest is infrastructure and hygiene: valid forward and reverse DNS (PTR) on your sending IPs, TLS on the connection, RFC 5322-formatted messages, and a spam-complaint rate kept under 0.3% in Google Postmaster Tools (aim below 0.1%). If any of that is missing, the unsubscribe header alone won't keep you in the inbox — Emailchaser's free SPF, DKIM and DMARC generators fix the authentication side, and the deliverability test checks the whole set in one pass.