List-Unsubscribe and One-Click Unsubscribe Explained

Open a newsletter in Gmail and you may see a small Unsubscribe link next to the sender's name. That is not part of the email body. It is drawn from a message header called List-Unsubscribe, and since 2024 the large mailbox providers expect bulk senders to support it in its one-click form.

What the header does

List-Unsubscribe tells the mailbox provider where and how a recipient can leave your list. The provider shows its own unsubscribe button in the message view, so the recipient does not hunt for a link at the bottom of your email. When someone clicks it, the provider either sends a small email to an address you give it, or makes a web request to a URL you give it.

Why this helps you: people who cannot find an unsubscribe link press "Report spam". Complaints hurt sender reputation far more than unsubscribes. A button that is easy to find turns would-be complaints into harmless removals.

The original header (RFC 2369)

List-Unsubscribe: <mailto:[email protected]?subject=unsubscribe>, <https://yourdomain.com/unsubscribe?token=abc123>

You can list a mailto: address, an HTTPS URL, or both. The angle brackets and the comma are required.

One-click unsubscribe (RFC 8058)

The newer standard adds a second header that says the HTTPS URL can be unsubscribed with a single POST request, with no confirmation page:

List-Unsubscribe: <https://yourdomain.com/unsubscribe?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

When the recipient clicks Unsubscribe, the mailbox provider sends an HTTP POST to your URL with the body List-Unsubscribe=One-Click. Your server must treat that request as the unsubscribe. No login, no extra questions, no "are you sure?".

Two details matter:

• The URL must be HTTPS, and the unsubscribe must work on a POST request (not only a click on a link in a browser).
• Both headers must be covered by your DKIM signature. If they are added after signing, or left out of the signed header list, providers may ignore them.

What the receiving endpoint should do

1. Identify the recipient from the token in the URL. Never use a plain email address in the URL, which would let anyone unsubscribe others.
2. On POST, mark the address as unsubscribed immediately. Return a 200 status.
3. Keep the suppression permanently so the address is never mailed again by this stream.
4. Honour it quickly. Google's rules say within two days, and sooner is better.

A tiny example in Node.js:

app.post('/unsubscribe', express.urlencoded({ extended: false }), async (req, res) => {
  const token = String(req.query.token || '');
  if (!/^[A-Za-z0-9_-]{16,64}$/.test(token)) return res.sendStatus(400);
  await suppressByToken(token);   // look up the subscriber by token and flag them
  res.sendStatus(200);
});

Keep a normal visible unsubscribe link in the body too, pointing to a GET page. Some clients ignore the header.

Who needs it

The rule is for marketing and subscription mail. Do not add an unsubscribe link to a password reset; it would be confusing and could let someone cancel important messages.

Common mistakes

• Unsubscribe requires login. That defeats the purpose.
• Token guessable. Use long random values.
• Header not signed. Add List-Unsubscribe and List-Unsubscribe-Post to the DKIM h= list, or check that your provider does.
• Slow processing. If you keep mailing people after they click, they will report you.
• Marketing and transactional mail in the same stream. Separate subdomains keep transactional mail free from the marketing rules. See transactional vs marketing email.

Where this fits with Mailions

Mailions is built for transactional email through the sending API and for business mailboxes, and the API takes the standard fields (from, to, subject, html, text, cc, bcc, reply_to) rather than custom headers. Transactional mail does not need an unsubscribe header. For newsletters and promotions, use a tool that manages subscriber lists and adds these headers for you, and keep that stream on its own subdomain. If you are unsure which category your mail falls into, contact us and describe what you plan to send.

Frequently asked questions

What is the List-Unsubscribe header?

An email header that gives mailbox providers a link or address for unsubscribing. Gmail, Yahoo and Apple Mail use it to show their own unsubscribe button, so recipients can leave without hunting for a link or reporting spam.

What is one-click unsubscribe?

Defined in RFC 8058, it adds a List-Unsubscribe-Post header so the provider can unsubscribe someone with a single HTTPS POST request, without opening a page. Gmail and Yahoo require it for bulk marketing mail.

How quickly must unsubscribe requests be honoured?

Gmail and Yahoo expect requests to be processed within two days. The US CAN-SPAM Act allows up to ten business days, but faster is better: each message after an unsubscribe is likely to be reported as spam.