List-Unsubscribe: The Two Headers Behind Gmail's Unsubscribe Button

Gmail and Apple Mail have shown an unsubscribe button at the top of emails for years. One tap and the user is off the list, without opening the message body. That button is driven by two standard mail headers: List-Unsubscribe tells the mail client where the unsubscribe endpoint is, and List-Unsubscribe-Post signals that a one-click POST is accepted — no page redirect needed. Without these headers, email platforms handle unsubscribes on their own terms, and your sending domain's reputation with those platforms takes a hit.

Rovela adds them automatically

As long as four conditions are met, Rovela adds both headers to every email without any configuration from you:

1. The request is associated with an organization (satisfied automatically when using an API key)
2. to has exactly one recipient
3. No cc or bcc
4. The system's BASE_URL starts with https://

The resulting headers look like:

List-Unsubscribe: <https://rovela.dev/unsubscribe/eyJ…/one-click>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Each token is tied to a specific send record, so the link is single-use in the sense that forwarded copies of the email carry a link that unsubscribes the original recipient only, not the person who forwarded it.

What happens when a recipient clicks unsubscribe

The mail client sends a POST to the URL in the List-Unsubscribe header. Rovela receives it and:

1. Adds the address to the suppression list with kind unsubscribed and origin manual
2. Future sends to this address are skipped and their status becomes suppressed
3. If you have a webhook configured, you receive an email.suppressed event with {email_id, to, reason}

You do not need to maintain your own unsubscribe database. Rovela records it and automatically blocks future sends to that address.

Marketing email vs transactional email

These headers are essential for marketing email: campaign blasts, promotions, newsletters. Google and Yahoo's bulk sender guidelines updated in early 2024 made this a hard requirement for high-volume sending.

For transactional email — password resets, order confirmations — the headers are optional and have no effect on deliverability either way. Transactional email is user-initiated; unsubscribing from it means the person no longer receives account-critical notices, so most senders leave the headers off for that category. If you're sending periodic content like a member newsletter, add them.

Conditions that suppress the headers

If to has more than one recipient, or cc/bcc is present, the unsubscribe headers are omitted — there is no clean per-person unsubscribe semantics for a multi-recipient message. For bulk campaign email, send each message as a separate request with one recipient per call, and the headers will appear.

A test domain or a BASE_URL that starts with http:// also suppresses the headers. Production environments are fine; in local development, check your BASE_URL if the headers are missing.

See the Send Email API reference for the full request format.