Unsubscribe links
A recipient of your marketing mail has two ways to opt out: the unsubscribe button their mailbox provider renders, and a link in the message body. We put both on every marketing send, report each opt-out as a webhook event, and suppress the address so your next campaign skips it. Setting the category correctly is the only part you own.
Set the category
An unsubscribe only means something for mail a recipient can opt out of, which is why the category comes first. A send is category: "marketing" by default, so campaign, newsletter, and announcement mail is handled correctly with no extra work. Set category: "transactional" explicitly on operational mail, and we leave it alone. A receipt or a password reset has no unsubscribe link and is never gated by someone's earlier opt-out.
Two obligations sit behind this. Bulk senders are required by Gmail and Yahoo to offer one-click unsubscribe on marketing mail, and a visible in-body link is separately required by law in most markets. A marketing send has both.
The one-click unsubscribe button
This is the unsubscribe control mailbox providers draw in their own interface, next to the sender name. It comes from a pair of headers, List-Unsubscribe and List-Unsubscribe-Post, and providers only offer the one-tap version when both are present and the opt-out endpoint accepts an unauthenticated POST with no confirmation step. That is the contract Gmail and Yahoo check for.
Marketing mail goes out with those headers already on it, however you send it: a broadcast from the dashboard, or a marketing message through POST /v1/email/messages. Nothing to build, nothing to host.
Because we own that header pair on marketing mail, setting your own List-Unsubscribe or List-Unsubscribe-Post on a marketing send is rejected with a 422. On a transactional send we add no unsubscribe header, and you can set your own through the headers field if you have a reason to.
A recipient using the provider's button produces an email.list_unsubscribed event.
The in-body link
The second path is a visible unsubscribe link in the message itself. We add one to the HTML body of your marketing sends, so a recipient always has something to click. You can add your own link too, pointing at a preference center you host, and ours stays alongside it as the compliant floor.
By default the link arrives as a small footer at the end of the body. To choose the spot yourself, put the reserved {{ bird.unsubscribe_url }} variable where the link belongs:
कोड उदाहरण
<p>
You received this because you subscribed to our newsletter. You can {{ bird.unsubscribe_url }} at
any time.
</p>We then render the link there instead of appending the footer, as an anchor whose text reads "unsubscribe". You can also use it as an href value (<a href="{{ bird.unsubscribe_url }}">Leave this list</a>) to keep your own wording and styling.
The substitution happens on the outgoing copy only, so reading the message back through the API returns your original content with the variable intact.
Brand where the link lands under Email → Unsubscribe page in the dashboard. It sets the sender name our unsubscribe page shows, which falls back to your organization name when you leave it empty, plus the background, text, and button colors, with a live example link to preview the result.
A recipient using the in-body link produces an email.unsubscribed event, distinct from email.list_unsubscribed so you can tell the two paths apart.
What an opt-out does
We stop mailing the recipient without you acting on the webhook. Either event adds the address to your workspace suppression list with reason unsubscribe and applies_to: non_transactional, which means:
- marketing sends to the address are rejected with email.rejected and rejection_reason: "recipient_suppressed".
- transactional sends still go through, because an unsubscribe says the recipient wants no more campaigns. The address itself still works.
The webhook events let you mirror the opt-out into your own database, flip a subscription flag, or log it. Both include the same identifying fields every email event includes (email_id, recipient_id, workspace_id, the recipient address and its recipient_role, plus the tags and metadata from the original send), so you can reconcile against your own records with no extra lookup. Subscribe to them the same way as any other email event; the events reference has the full payloads.
To inspect or undo an opt-out, the suppression record has source_email_id and source_recipient_id linking back to the message that caused it, and you can remove it through the suppressions API.
Next steps
- Categories: why marketing is what makes an unsubscribe take effect
- Suppressions: the list unsubscribes land on, and how to manage it
- Email events: the full email.unsubscribed and email.list_unsubscribed payloads
- Gmail and Yahoo requirements: where one-click unsubscribe is required for bulk senders
- Webhooks: subscribing an endpoint, signature verification, and retries