The List-Unsubscribe header: what it is, who requires it, and when Notix sets it.
Two headers let a mail client show its own Unsubscribe control at the top of a message and act on it with one request. Gmail and Yahoo have required them from bulk senders since February 2024. Notix adds them to every campaign and journey send and leaves them off receipts and codes on purpose. This page shows the headers, the request, and the rule for each kind of mail.
The two headers.
List-Unsubscribe carries where an unsubscribe request goes: an https URL, a mailto address, or both in angle brackets. On its own it lets a client show an Unsubscribe link, but the client has to open the URL and the reader still lands on a page. List-Unsubscribe-Post, defined in RFC 8058, adds the value List-Unsubscribe=One-Click and promises that a single POST to the URL with that body unsubscribes the reader with no page, no login and no confirmation. That promise is what lets Gmail act on the header instead of merely linking to it.
From: Acme <news@mail.acme.com>
To: ada@example.com
Subject: October at Acme
List-Unsubscribe: <https://app.usenotix.dev/api/unsubscribe-oneclick?id=cmp_9f2k-ct_31a&hash=…&source=campaign>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Precedence: bulk
When the reader clicks Unsubscribe in Gmail, the client sends the request the second header promised:
POST /api/unsubscribe-oneclick?id=cmp_9f2k-ct_31a&hash=…&source=campaign HTTP/1.1
Host: app.usenotix.dev
Content-Type: application/x-www-form-urlencoded
List-Unsubscribe=One-Click
The link is signed for the contact and the campaign or journey it came from, so a forged request cannot unsubscribe someone else, and the endpoint only accepts links signed for one-click use. Precedence: bulk goes on the same sends; it is older and weaker, but some auto-responders still honour it.
Who requires it, and from whom.
Google’s email sender guidelines (read on 13 September 2026) say that senders of 5,000 or more messages a day to Gmail must support one-click unsubscribe on marketing and subscribed messages, with both headers present, alongside SPF and DKIM, a DMARC record, an aligned From domain, and a spam rate kept below 0.30% with 0.10% as the working ceiling. Yahoo’s sender best practices (read the same day) require bulk senders to implement a functioning List-Unsubscribe header that supports one-click unsubscribe under RFC 8058, to honour the request within two days, to pass DMARC with a policy of at least p=none, and to keep the spam rate below 0.3%. Enforcement at both began in February 2024.
Neither provider asks for the header on transactional mail, and neither should you add it there. The requirement is about mail people subscribed to and may want to stop; a receipt is not that.
What Notix does, by kind of send.
The rule is simple: a send with a list behind it gets the headers and honours the click at send time; a send without one gets neither.
| Kind of send | Headers | On click | Later sends to that contact |
|---|---|---|---|
| Campaign | Set for you: List-Unsubscribe with a signed one-click link, List-Unsubscribe-Post, Precedence: bulk. | The contact is marked unsubscribed from the book, with the reason recorded, and a contact.unsubscribed webhook fires. | Refused at send time to an unsubscribed contact. |
| Journey step | Set for you, the same pair, with a link that names the journey. | As above, and the contact's active journey runs end. | Refused at send time to an unsubscribed contact. |
| Transactional (API or SMTP) | Not set. There is no list to leave, and a receipt or a code must not carry a way to stop the next one. | Not applicable. | Goes out regardless of subscription. Only a suppressed address (hard bounce or complaint) is dropped. |
| Your own header | If your send sets List-Unsubscribe or List-Unsubscribe-Post itself, Notix leaves yours in place and does not add its own. | Your endpoint's behaviour. | Your rule. |
An unsubscribe and a suppression are different lists. The unsubscribe is a preference on the contact book: marketing mail stops, transactional mail continues. The suppression list is for addresses that must never be mailed again, hard bounces and complaints, and it applies to every kind of send. Keeping them apart is what lets a customer leave your newsletter and still get their receipt.
If you send marketing mail through the transactional API rather than a campaign, the headers are yours to add in the send request’s headers field, pointing at an endpoint of yours that accepts the one-click POST. Notix leaves a header you set in place and never overwrites it. The notification email page shows which notices belong on which side of that line.
Why it matters beyond compliance.
A reader who cannot find the unsubscribe link presses the spam button instead, and a complaint counts against your domain in a way an unsubscribe never does. Google’s spam-rate lines are on email deliverability; the causes of spam placement, of which a missing unsubscribe is one, are on emails going to spam. The pre-send check blocks a marketing message with no unsubscribe link in its body for the same reason: the header covers the client’s button, the link covers the reader who scrolls.
Questions, answered.
What is the List-Unsubscribe header?
What do Gmail and Yahoo require for one-click unsubscribe?
How do I add one-click unsubscribe to my emails?
Should transactional emails have a List-Unsubscribe header?
What happens when someone clicks unsubscribe?
Is an unsubscribe the same as a spam complaint?
Keep reading.
Email suppression lists
Why a suppression list exists, the three reasons an address lands on it, and why one list across transactional and marketing matters.
LearnEmail deliverability and sender reputation
What mailbox providers score, the complaint threshold that matters, warming a new domain, and the honest position on shared IPs.
LearnWhy transactional emails go to spam
The seven causes, in the order to check them, and what Notix already handles versus what is still yours.
Use casesNotification email
Product notifications from templates, batched when they fan out, with delivery events back through webhooks.
NotixDocs
The quickstart: verify a domain, copy an API key, send the first email.
Send a campaign and see the headers on it.
One-click unsubscribe, a signed link and the click recorded against the right contact, without configuration.