One-click unsubscribe

Send with list_unsubscribe and we add the two RFC 8058 headers that make a mail client's own unsubscribe button work:

{
  "from": "Acme <hello@mail.yourdomain.com>",
  "to": ["customer@example.com"],
  "subject": "This month at Acme",
  "html": "<p>Here's what shipped.</p>",
  "list_unsubscribe": true
}

When the recipient uses it, we add their address to your suppressions with reason unsubscribe, and every later send to that address is skipped automatically. You don't have to process anything.

Show a visible unsubscribe link

Mail clients show their own unsubscribe button from the headers, but Gmail and Yahoo also expect a link people can see in marketing mail. Put {{unsubscribe_url}} anywhere in your HTML or text and we replace it with this message's one-click link:

<p style="font-size:12px">
  Don't want these emails? <a href="{{unsubscribe_url}}">Unsubscribe</a>
</p>

• Using the tag turns list_unsubscribe on for that message, so the headers and the visible link always agree.
• It needs a single recipient (see below); a send to several people with the tag is refused with a validation_error telling you to split it.
• The link is never click-tracked, and it's filled in when the message goes out - your stored message keeps the tag, so previews stay readable.

Know when someone unsubscribes

Subscribe a webhook endpoint to email.unsubscribed to update your own list the moment it happens. It fires once per message, the first time the recipient unsubscribes; data.to is who asked.

{
  "type": "email.unsubscribed",
  "created_at": "2026-09-24T09:12:04.000Z",
  "data": { "email_id": "…", "to": ["customer@example.com"], "subject": "This month at Your Company" }
}

Turn it on for everything

Settings → Sending defaults applies it to all your mail. list_unsubscribe on a send overrides that either way, so an account that offers unsubscribe on its campaigns can still send one message that doesn't:

{ "subject": "Reset your password", "list_unsubscribe": false }

Leave it off for transactional mail

An unsubscribe link on a password reset offers to stop messages the recipient still has to receive. It is a promise you cannot keep, and it trains people to click something that won't work. Marketing opts in; receipts, resets and security alerts stay quiet.

Single recipient only

The headers are written once per message, and every recipient gets the same pair. On a message addressed to three people, an unsubscribe can't say which of them asked — so the choice would be to unsubscribe all three or none.

We attach the headers only when a message has exactly one recipient, counting cc and bcc. Bulk mail is sent one message per recipient anyway, which is exactly the shape this serves. A message with more recipients is sent normally, just without the headers.

What the link does

The split matters. Corporate mail scanners and link-preview bots follow every URL in a message with a GET — if that unsubscribed, a scanner would silently remove people who never asked, and they'd find out months later by not receiving something.

The link carries a signed token naming the message, never the recipient's address: an address in a URL leaks into browser history and proxy logs. It is scoped to unsubscribing, so an open-tracking URL from the same message will not work on it.

Reversing one

An unsubscribe is a suppression like any other. Remove it from the suppressions page if the recipient asks you to — and only then.