Braze Step-By-Step Guide: Email Preference Center Setup (No Engineering Resources Required!)
This highly-requested guide is back! Read on to learn how to use Braze Webhooks to set up your Braze Preference Center and avoid losing your email subscribers from a single click.
This guide was posted a few years ago in the Braze Slack Community; however, in the original guide, it was missing one crucial step around rate limiting. This updated guide will be sure to cover all the important steps.
Let’s get right into it!
Step 1: Create the Subscription Groups
After all, it wouldn’t really be a Preference Center without any Subscription Groups, right? The first step is to create the Subscription Groups that will be shown in the Preference Center. Navigate to Audience → Subscriptions, and create as many Subscription Groups as needed.
Keep in mind that the “Description” will be shown to your users, and we’ll need the “Subscription Group ID” in a later step.
FYI: all dashboard steps will be provided under the new navigation to keep up with the latest changes. We know, it pains ustoo; it’s many years of worth of process change 😭.
When your users click the “Manage Email Preference” link in your email footer, the Subscription Groups will be the options shown to your users to possibly avoid losing their email subscription entirely.
Step 2: Set Up a Webhook to Subscribe New Users
Typically, when your users sign up on your website or your mobile app with their email address, a new Braze user profile will be created. For users who gave consent to be subscribed to email, their global email subscription status will either be subscribed or opted-in.
In addition to their global email subscription status, we will need to subscribe them to each Subscription Group that exists in the Preference Center.
Think about it this way: if there’s a leak in the ceiling, there’s no point of cleaning up the mess on the floor unless we fix the leak first. Similarly, we will first set up the Braze Webhook that’ll subscribe the downstream of new users into the Subscription Groups. Then, we will tackle the existing users in a later step.
Step 2a: Create an API Key with permissions to subscription.status.set.
If you’re not sure how to create an API key, keep an eye out for a blog explaining this! Here’s the subscription/status/set API Doc.
Step 2b: Create a Webhook Campaign
Name it something like “Add NEW USERS To Email Subscription Groups”, and choose “Blank Template”.
Step 2c: Insert WEBHOOK URL
Look at your Braze dashboard URL to determine which cluster you’re in. Then choose one of the URLs below to input into “Webhook URL”.
https://rest.iad-01.braze.com/subscription/status/set
https://rest.iad-02.braze.com/subscription/status/set
https://rest.iad-03.braze.com/subscription/status/set
https://rest.iad-04.braze.com/subscription/status/set
https://rest.iad-05.braze.com/subscription/status/set
https://rest.iad-06.braze.com/subscription/status/set
https://rest.iad-08.braze.com/subscription/status/set
https://rest.fra-01.braze.eu/subscription/status/set
https://rest.fra-02.braze.eu/subscription/status/set
Step 2d: Add Key/Value Pairs
We’re going to add 4 Key/Value Pairs (KVPs). You could also choose “Raw Text” for your Request Body, but for this webhook, it might be easier to use the Braze UI.
The 4 KVPs you’ll add are:
- email : {{${email_address}}}
- external_id : {{${user_id}}}
- subscription_state : subscribed
- subscription_group_id : YOUR_SUBSCRIPTION_GROUP_ID
Step 2e: Add Request Headers
Click the “Settings” tab, and add the two request headers:
- Content-Type : application/json
- Authorization : Bearer YOUR_API_KEY
This is usually the set up for almost every POST request in Braze.
Step 2f: Set Trigger
Choose “Add an Email Address” for the trigger, and click “Add Trigger”. “Add an Email Address” will trigger whenever an email address is added on a user profile for the first time. This will not trigger for any changes in the email address (which is good for our use case).
Pro Tip: This out-of-the-box trigger can actually substitute for custom events like “USER_SIGNUP”, “CREATE_ACCOUNT”, etc., as long as an email address is guaranteed for every new user signup.
Make sure to uncheck re-eligibility; we do not want users to receive this webhook more than once.
Step 2g: Set Audience
In the Target Audiences, add the two filters below to make sure only subscribed or opted-in users get this webhook.
CRUCIAL STEP: Make sure to set the rate limit to 5000 requests per minute.
This is the crucial mistake we mentioned in the beginning of the post. Every API Endpoint has a specific rate limit; for /subscription/status/set, it’s 5000 requests per minute.
This is a limit set by Braze to make sure that their servers are not being overloaded with API calls, and if your webhook campaigns do not respect these limits, they can, have, and will stop your webhook campaigns.
This setting will make sure that in the case of any high-volume user activity (e.g. grand opening), that only 5000 webhooks will get sent out each minute.
Lastly, make sure that there is no control group or variants.
Step 2h: Launch & Duplicate!
A conversion event isn’t too necessary for this webhook since this use case is purely operational. Launch the campaign, and check that all new users moving forward are subscribed into the Subscription Groups!
Note: After launching one webhook campaign, this campaign will have to be duplicated and launched for every single Subscription Group. The only information to change for each campaign is to swap out the Subcription Group ID.
Step 3: Set Up Backfill Webhook
Now that we’ve fixed the leak in the ceiling, it’s time to clean up the mess — by backfilling all the existing users into the new Subscription Groups. This will just be a one-time webhook launch to make sure all the users are in the Subscription Groups so they can actually receive future emails from those groups.
This webhook campaign will actually look very similar to the campaign from Step 2, so we’re actually going to duplicate each campaign again (we’ll need one backfill webhook for each Subscription Group again).
By the end of this setup, you’ll have 1. a downstream webhook and 2. a backfill webhook for each Subscription Group you create.
There’s a few changes to make on these backfill webhooks:
Step 3a: Change the Delivery Type to Scheduled: Send immediately
Step 3b: Change the Audience Filters
This way, you’re only targeting the users who agreed to receive email.
Same rate-limit and control group settings apply here. The rate-limit is actually a bigger concern when backfilling users because there’s a much higher chance that you’re sending to more than 5000 users per minute in a backfill campaign than a downstream campaign.
Step 3d: Launch and check User Profile → Engagement
Check that the Subscription Group toggles are on after launching each backfill webhook! If they’re not toggled on, please feel free to reach out at allan@fornowmarketing.com or DM me on LinkedIn. There are plenty of small mistakes that could be causing this issue.
Step 4: Include the Correct Email Preference Link in all Email Footers
By this point, all existing, eligible users should be added to each Subscription Group, and all new users should fall under each Subscription Group automatically. Now it’s time to give the users the capability to visit your shiny, new Email Preference Center.
You were mostly likely hyperlinking {{${set_user_to_unsubscribed_url}}} in your “Unsubscribe” button. We recommend changing the copy from “Unsubscribe” to “Manage Email Preferences”.
Then, make sure to hyperlink {{${preference_center_url}}} moving forward so that whenever a user clicks on “Manage Email Preferences”, they’re redirected to your Email Preference Center and not to the unsubscribe page.
Btw, this is one reason why using a global, Custom Email Footer is so important. If you’re having to manually change out the footer in each email campaign… we wish you good luck.
Step 5: Add the Appropriate Audience Filters in New Campaigns Moving Forward
A wise man once said: “Remember, with great power comes great responsibility.”
Now that you have the great power of allowing users the option to subscribe to specific type of emails via the Subscription Groups, you also have the great responsibility of remembering to respect the users’ subscriptions and only send the emails to the users who want to receive those emails.
For all future email campaigns, it is strongly recommended to choose the Subscription Group audience filter and only send to users who agreed to receiving that specific type of email campaigns.
For example, if a user explicitly decided to only sign up for Promotional emails but still received your next Newsletter, that’s a very quick way to lose trust from the user and risk being marked as spam.
Conclusion
Hopefully, this is the longest blog we’ll ever write. However, it’s jam-packed with important details and super-technical setup instructions that were very exciting to put together. Please let us know if you have any questions along the way, and stay tuned for more supplemental blogs on some of the topics covered today!
Thank you!
Thank you for reading, and please reach out with any questions.
fornowmarketing.com
allan@fornowmarketing.com
