Skip to content
DocumentationAPI reference Build something worth sending.

Guides

The List-Unsubscribe header and one-click unsubscribe

How List-Unsubscribe and List-Unsubscribe-Post work, what Gmail and Yahoo ask of bulk senders, and which emails need the header and which do not.

List-Unsubscribe is an email header that gives mailbox providers a way to unsubscribe someone without opening the message. Gmail, Yahoo and Apple Mail show it as an Unsubscribe link next to the sender. Since 2024, Gmail and Yahoo require one-click unsubscribe on marketing mail from bulk senders.

The two headers

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

List-Unsubscribe (RFC 2369) lists one or more addresses in angle brackets, separated by commas: an HTTPS URL, a mailto:, or both.

List-Unsubscribe-Post (RFC 8058) turns the HTTPS URL into a one-click link. When the reader clicks Unsubscribe, the mailbox provider sends a POST to that URL with the body List-Unsubscribe=One-Click. Your server removes the address. Nobody sees a confirmation page.

What one-click needs to work

  • An HTTPS URL in List-Unsubscribe. A mailto: alone does not count as one-click.
  • A URL that identifies the recipient and the list on its own, usually with a signed token. The POST carries no cookie or login.
  • An endpoint that accepts the POST and unsubscribes straight away. Do not redirect it to a page that asks "are you sure?"
  • A DKIM signature that covers both headers, so they cannot be added or changed in transit.
  • The unsubscribe honored within two days. That is the window Gmail and Yahoo give bulk senders.

Who has to send it

Gmail's rules apply to senders of about 5,000 or more messages a day to Gmail addresses, and Yahoo's are similar. Those senders need one-click unsubscribe on marketing and promotional mail, along with SPF, DKIM, a DMARC record and a low spam complaint rate. Smaller senders are not required to add it, but it still helps: a reader who can unsubscribe in one click is less likely to press Report spam.

Transactional email does not need it

Password resets, receipts, sign-in codes and security alerts are not subscriptions, and the bulk-sender rule exempts them. Adding an unsubscribe header to a password reset invites people to turn off mail they need. Keep transactional and marketing mail separate, ideally on different sending addresses or subdomains, so a newsletter's complaint rate does not drag down your receipts.

How SendPanda handles it

Broadcasts sent from SendPanda get both headers on every message, with a signed one-click URL for each contact. SendPanda receives the POST, unsubscribes the contact, and keeps them out of later broadcasts. You do not build the endpoint. Emails you send through the API are treated as transactional and do not get the header. See transactional email and newsletters for how the two fit in one account.

Check a message

Send a test to a Gmail address, open it, and choose Show original. Look for both headers, and for dkim=pass in Authentication-Results. If the Unsubscribe link does not appear next to the sender, Gmail may be holding it back until the domain has a sending history, which is normal for a new domain.

Next steps

↑↓ to navigate↵ to openesc to close