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 record the address's opt-out 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 the message header. 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:
Contoh kode
<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.
Customize the destination page in Email > Unsubscribe page. Set its sender name, background, text, and button colors. The sender name defaults to your organization name. Use the 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 records the recipient's address as unsubscribed from non-transactional mail, which means:
- marketing sends to the address are rejected with email.rejected and rejection_reason: "recipient_suppressed". That reason reports any recipient-level block, a suppression or a stated preference alike, so it is the one to match on either way.
- transactional sends still go through, because an unsubscribe says the recipient wants no more campaigns. The address itself still works.
An unsubscribe is a stated preference, not a suppression: it shows up on the Preferences tab of Email > Suppressions, and on the contact's detail page, rather than in the suppression list. Only that address is affected, and the record shows who opted out and when.
The webhook events let you mirror the opt-out into your own database, flip a subscription flag, or log it. Both include the identifying fields from every email event: email_id, recipient_id, workspace_id, the recipient address, and its recipient_role. They also include the original send's tags and metadata, so you can reconcile against your records without another lookup. Subscribe to them the same way as any other email event; the events reference has the full payloads.
An unsubscribe is the recipient's own statement, so you can't remove it through the suppressions API the way you would a suppression. To resume mailing the address, record an opt-in on Contacts > Preferences, or call POST /v1/preferences with status: granted. That workspace-wide page records statements for every channel, while the tab on Email > Suppressions shows the email ones. Either way, granting over their opt-out needs consented_at, the moment the recipient consented, and the opt-in takes effect only when that moment is after the opt-out it reverses.
Next steps
- Categories: why marketing is what makes an unsubscribe take effect
- Suppressions: the deliverability-fact list, and how it differs from a stated preference
- 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