The List-Unsubscribe header, explained
Updated
The List-Unsubscribe header is a line hidden in the technical headers of a newsletter that tells mail apps how to unsubscribe you. It is why Gmail and Apple Mail can show an Unsubscribe button next to the sender. This page explains how it and the one-click standard work, and how a tool can use them safely.
What the header looks like
It is part of the email's headers, not its visible body. A typical one has two options, a web address and an email address, each inside angle brackets:
List-Unsubscribe: <https://news.example.com/u?t=abc>, <mailto:unsub@news.example.com?subject=unsubscribe>It was defined in RFC 2369 in 1998, together with other list headers such as List-Id. In Gmail you can see it with "Show original" on a message; in Apple Mail, View → Message → All Headers.
Three ways to unsubscribe
- mailto. The mail app sends a short email to the address in the header. The sender's system reads it and removes you.
- A link. The mail app opens the web address, usually a page where you confirm.
- One-click (RFC 8058). The sender adds a second header,
List-Unsubscribe-Post: List-Unsubscribe=One-Click, and an HTTPS address. The mail app then sends a POST request with that fixed body, and the sender must unsubscribe you without showing a page or asking anything.
Why one-click matters
RFC 8058 was published in 2017 so that unsubscribing is a single action, safe to automate, rather than a web page that can be a trap. Since 2024 Google and Yahoo require senders of bulk marketing mail to support one-click and to act on it within two days, so most large newsletters now offer it. Small senders may still offer only a link or a mailto, or no header at all.
Security rules a tool should follow
- Read the target from the message, never from the user. Otherwise the feature becomes a way to send requests or mail to any address.
- Only HTTPS for one-click, only public addresses. Requests to internal or private network addresses must be refused.
- Don't follow redirects on a one-click request, and send only the fixed body.
- Ignore extra mailto fields. A mailto link can carry cc, bcc or body fields; only the address, the subject and a short body should be used.
- Ask the user first. Sending an unsubscribe email is sending email from the user's mailbox.
NeoCEO's Subscriptions view follows these rules: the server reads the header, picks one-click, then mailto, then the link, and only after you confirm.
What the header doesn't do
NeoCEO connects Gmail and IMAP mailboxes; Outlook and Microsoft 365 accounts are not supported.
It is only as honest as the sender. Real mailing lists honor it; spammers often include it but ignore it, which is why unknown senders are better reported as spam. And not every newsletter has it, so some unsubscribe links still have to be used by hand.
List-Unsubscribe: questions
What is the difference between RFC 2369 and RFC 8058?
RFC 2369, from 1998, defines the List-Unsubscribe header with its mailto and link options. RFC 8058, from 2017, adds the one-click mode: a second header, List-Unsubscribe-Post, and a POST request with a fixed body that unsubscribes you without showing a web page. Most large senders now support both, because Google and Yahoo require one-click for bulk marketing mail since 2024, so you will rarely meet a large newsletter without it.
How can I see if an email has it?
Open the message's full headers (Show original in Gmail, or View, Message, All Headers in Apple Mail) and look for a line that starts with List-Unsubscribe. If it is there, your mail app can usually offer an Unsubscribe button next to the sender. If it is missing, the sender either does not run a proper mailing list or left the header out, and you have to use the link in the email body.
Does one-click unsubscribe work for everyone?
Only for senders that support it, which is most large ones since 2024. Others fall back to an unsubscribe email or a link you open, and small senders may offer no header at all. This is why NeoCEO picks the method per sender, one click first, then an email from your mailbox, then a page, and asks for your confirmation before sending anything.
Is the List-Unsubscribe header a security risk?
The header itself is harmless, but a tool that follows it blindly can be abused. Safe tools read the address from the message on the server, accept only HTTPS for one-click, refuse internal network addresses, ignore redirects and extra mailto fields, and ask the user first. Spam can include the header too, so unknown senders are better reported as spam than unsubscribed.
Do I need the header if I send newsletters?
Yes, if you send marketing email in bulk. Google and Yahoo have required large senders to support one-click unsubscribe and to process requests within two days since 2024. Even for small lists it helps: recipients who can leave easily report you as spam less often, which protects your sender reputation and keeps your real mail reaching the inbox instead of the spam folder.
Free to start, no card: see the pricing and how NeoCEO handles your mail in the privacy policy.