# List-Unsubscribe and One-Click Unsubscribe Explained

> The List-Unsubscribe header adds an unsubscribe button in Gmail and Yahoo. Learn how one-click unsubscribe (RFC 8058) works and how to implement it correctly.

Published 2026-10-29. Source: https://mailions.com/blog/list-unsubscribe-header

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](/blog/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:unsubscribe@yourdomain.com?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:

```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

| Mail type | One-click required? |
|---|---|
| Newsletters, promotions | Yes, for bulk senders to Gmail and Yahoo |
| Transactional (receipts, resets, codes) | No |
| One-to-one business email | No |

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](/blog/transactional-vs-marketing-email).

## Where this fits with Mailions

Mailions is built for transactional email through the [sending API](/help/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](/contact) 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.