List-Unsubscribe

Modern senders ship two headers: List-Unsubscribe (a URL or mailto: the user can hit), and List-Unsubscribe-Post (RFC 8058 — declares that the URL accepts a one-click POST). With both present, mail clients render a real button that POSTs to your endpoint and shows a confirmation, no page-load required.

List-Unsubscribe: <https://yourdomain.com/u/abc123>, <mailto:unsubscribe@yourdomain.com?subject=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

As of February 2024, Gmail and Yahoo require a List-Unsubscribe-Post header from any sender over 5000 messages/day to a Gmail or Yahoo recipient. Without it, your mail gets aggressively rate-limited or rejected.

The rules also require a complaint rate below 0.3% sustained — which the one-click unsub directly helps with, by giving annoyed recipients a one-click way out that does not involve hitting "Report spam".

The endpoint named in List-Unsubscribe must accept a POST with body List-Unsubscribe=One-Click. Look up the user by the token in the URL, add them to your suppression list, return 200. The mail client shows "Unsubscribed" in the UI on a 2xx.

app.post("/u/:token", async (req, res) => {
  const body = await req.text();
  if (body !== "List-Unsubscribe=One-Click") return res.status(400).send();

  const token = req.params.token;
  const sub = await db.subscriber.findUnique({ where: { unsub_token: token } });
  if (!sub) return res.status(404).send();

  await db.suppression.create({
    data: { address: sub.email, kind: "unsubscribe", created_at: new Date() },
  });
  res.status(200).send();
});

SNDR's outbound MTAs add List-Unsubscribe-Post to every send automatically. The customer only needs to publish a List-Unsubscribe URL on their side; SNDR signs the request, your endpoint receives it with the suppression token, and our suppression layer is updated via the resulting webhook.

For broadcast / marketing sends, this is non-optional infrastructure. For pure transactional sends (password resets, OTPs), the header is omitted because recipients cannot opt out of mail they explicitly requested.