Braze is the enterprise customer engagement platform serving global B2C brands (streaming, retail, ride-share, financial services) with email, SMS, mobile push, in-app messaging, and Content Cards from a real-time data model. The unsubscribe mechanism uses the Liquid-style merge tag in email templates, and Braze handles RFC 8058 one-click headers automatically once the domain is authenticated. Subscription groups let users opt out of one topic (Weekly Digest, Promotions) without leaving all Braze communication. This guide covers the tag, the subscription group model, and the enterprise-specific issues with campaign send-time filters.
Braze unsubscribe link
| Tag syntax | {{${set_user_to_unsubscribed_url}}} |
| Placement | Auto-embedded in every campaign footer |
| Scope | Per Subscription Group, plus master subscription state |
| Config path | Settings > Subscription Group Management |
| RFC 8058 one-click | Yes, automatic for marketing campaigns with authenticated domain |
How to add the unsubscribe tag in Braze
Place the merge tag exactly as shown below in the email template. Braze replaces it at send time with a signed URL scoped to the recipient and campaign.
{{${set_user_to_unsubscribed_url}}}For custom HTML templates, wrap the tag in an anchor to render a proper hyperlink in the delivered email:
<a href="{{${set_user_to_unsubscribed_url}}}">Unsubscribe from this list</a>Auto-embedded in every campaign footer
Yes, automatic for marketing campaigns with authenticated domain The recipient's mailbox provider (Gmail, Yahoo) uses the List-Unsubscribe-Post header to expose the native one-click button on the message. Requires domain authentication with DKIM and DMARC.
Braze campaigns filter recipients on the subscription state at send time, but subscription groups act as an override. A user unsubscribed from the master subscription state can still receive from a subscription group where they are explicitly opted in. Use the "Global Unsubscribe" API endpoint for true account-wide opt-out on GDPR erasure requests.
Testing your Braze unsubscribe link
- Send a test message to a controlled Gmail address you own via the Braze campaign preview action
- Click the footer unsubscribe link and confirm the opt-out on the landing page
- Check the subscriber or contact record: the status should be Unsubscribed within seconds
- Verify the RFC 8058 headers in Gmail: open the message, click three dots, then Show original. Look for
List-UnsubscribeandList-Unsubscribe-Post: List-Unsubscribe=One-Click
Want the full 222-platform reference?
See the pillar guide with the compliance landscape, the RFC 8058 deep dive, and the unsubscribe tag for every ESP: How to add an unsubscribe link: the complete 2026 guide →
The Braze subscription group model
Braze uses subscription groups as its opt-out primitive. Each subscription group represents a topic (Weekly Digest, Product Updates, Promotional Offers) that users can opt into or out of independently. Every marketing campaign is sent through a specific subscription group, and users who have opted out of that group are automatically excluded from the send. This granular model is what distinguishes Braze from simpler platforms that offer only account-wide unsubscribe: enterprise brands can honor topic-specific preferences without losing the marketing relationship entirely.
The Liquid unsubscribe tag
Templates in Braze use the {% subscription_group_unsubscribe %} Liquid tag or the associated {{${set_user_to_unsubscribed_state_by_email}}} helper to render the unsubscribe URL. The tag is placed inside an anchor: <a href=”{{unsubscribe_url}}”>Unsubscribe</a>. Braze also supports a Preference Center feature that renders a full topic-management page instead of a single opt-out, useful for brands with many subscription groups. The Preference Center URL is generated with {{preference_center_url}} in the template.
RFC 8058 and enterprise deliverability
Braze handles RFC 8058 one-click unsubscribe headers automatically once the sending domain is authenticated in the Braze dashboard (SPF, DKIM, custom Return-Path). The platform injects List-Unsubscribe and List-Unsubscribe-Post headers on every marketing send. Enterprise Braze deployments typically have full domain authentication as a prerequisite for launching, so most accounts satisfy the Gmail and Yahoo requirements from launch. Transactional messages sent through Braze Campaigns configured as transactional do not include unsubscribe headers, matching the standard convention.
Common enterprise pitfalls
Two issues recur in Braze deployments. First, teams sometimes forget to associate a Campaign with a Subscription Group, resulting in sends that reach users who intended to unsubscribe from that topic. The Campaign builder shows a warning but does not block the send. Second, custom-authored HTML templates occasionally omit the Liquid unsubscribe tag entirely, and while Braze surfaces a warning, senders can force the campaign live. Regular Campaign QA against a checklist that includes Subscription Group assignment and Liquid tag presence catches these before launch.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
