BeginnerCompliance · 5 min read

List-Unsubscribe — the new compliance line

Since February 2024 Gmail and Yahoo require a one-click unsubscribe header on every bulk email — and a working endpoint that honours it within 48 hours.

In February 2024 Gmail and Yahoo announced the largest sender requirements update in a decade. Among them: bulk senders (>5,000 messages a day to Gmail) must include a one-click List-Unsubscribe header and honour the unsub within 48 hours. Failing senders go to spam, and there are no warnings.

The two headers

httpList-Unsubscribe: <https://acme.dev/u/{token}>, <mailto:unsub+{token}@acme.dev>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

List-Unsubscribe lists one or two unsub URLs (HTTPS preferred, mailto: as a fallback). List-Unsubscribe-Post tells the receiver "this URL accepts an HTTP POST with no body to unsubscribe" — the magic that lets Gmail render the one-click button in the inbox.

The endpoint

The HTTPS endpoint must accept a POST request, return 200 OK, and persist the unsubscribe within 48 hours. Most one-click POSTs come from Gmail's anonymising proxy — your code never sees the actual user IP.

Do not redirect the POST to a marketing-style "are you sure?" page. The request is from a bot, not a human. Persist the unsub immediately, return 200, end of story.

Other 2024 requirements

SPF + DKIM + DMARC alignment with the From: domain (mandatory for bulk senders).
DMARC policy of p=none or stricter (must publish a record).
Spam-complaint rate kept under 0.3% (and below 0.1% sustained).
A valid List-Unsubscribe with one-click POST.

In VoltMail: every bulk send gets a per-recipient one-click token automatically. Our endpoint persists the unsub in <200ms server-side. You can override the destination URL for white-label use cases.