Skip to main content

Braze Integration Guide

Updated

How Wunderkind Integrates With Braze

The Braze integration with Wunderkind will enable us to collect and send new email addresses to your Braze, verify subscription status before sending an email, and update a user’s subscriber status if they unsubscribe. 

This guide includes an overview of everything that Wunderkind can and cannot support, considerations, requirements placed on us by Braze, and more.

Wunderkind requires UI access to Braze in order to build and test our integration with your Braze instance.

Table of Contents:

  1. Authentication
  2. Writing New Subscribers
  3. Checking Customer Status
  4. Checking Mailability
  5. Updating Unsubscribe Status
  6. Sender Options
  7. URL Appending
  8. Important Callouts

1. Authentication

Wunderkind uses a standard bearer token to authenticate with your Braze instance. 

We’ll need the following API Key permissions for our integration:

  • campaigns.trigger.send
  • email.status
  • subscription.status.get
  • subscription.status.set
  • users.export.ids
  • users.track

2. Writing New Subscribers

Upon email submission, Wunderkind will write new subscribers to Braze through the API calls below. We can write new subscribers in the following ways:

  • Adding new users is done using the Braze “users track” endpoint: https://www.braze.com/docs/api/endpoints/user_data/post_user_track/
    • We can create a new user to Braze using an external ID or an alias name/label
    • The external ID can be a SHA256-hashed-email address (email is made uppercase or lowercase prior to hash), or the user’s plaintext email address
    • Users can optionally be added to one or more subscription group
    • Events can optionally be added to the payload in addition to dynamically attributes
  • Retrieve existing user profiles is done using the Braze “users export IDs” endpoint: https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/
    • This would be used, for example, to resubscribe users who are already in Braze and update their profile data.
    • This is also used to check email_subscribe status on the profile for purposes of rejecting duplicate subscribers. Can also reject duplicate subscribers on the basis of profile existence.

Additional attributes may be sent to Braze. If a user is being updated, their existing properties can remain unchanged upon update or updated, optionally. Attributes that are arrays can be merged, with new properties being added to the existing array e.g. subscription groups.

SMS opt-ins can be captured either alongside email or in a separate SMS only campaign. SMS opt-in status is checked against a subscription list (not a profile attribute).

 

API Calls for Writing New Subscribers

Request with external_id
POST /users/track HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json
{
"attributes" : [{
"_update_existing_only": true/false,
"email": "{{email}}",
"email_subscribe": "subscribed",
"external_id": "{{see notes above}}",
“Properties”: {
“Source”: “wunderkind” // dynamic
}
}]
}
Request with user_alias
POST /users/track HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"attributes" : [{
"_update_existing_only": true/false,
"email": "{{email}}",
"email_subscribe": "subscribed",
"user_alias": {
“alias_name”: “{{email}}”,
“alias_label”: “{{dynamic_value}}”
},
“Properties”: {
“Source”: “wunderkind” // dynamic }
}]
}

 

3. Checking Customer Status

We can check for a user’s customer status in two ways: 

  1. Subscription Group: Check if a user has a specific subscription group id included in the list of subscription groups on their profile. This would be subscription group that represents a list of Customers.
  2. Profile attribute check: Wknd can look up an attribute on the user’s profile. The name of the attribute that indicates a status of customer must be provided.

Choosing between the two methods will depend on how Customer status is maintained within the client’s Braze account.

Subscription Group Check is done using Braze’s “List user’s subscription group status” endpoint: https://www.braze.com/docs/api/endpoints/subscription_groups/get_list_user_subscription_groups/

Export User Profile is done using Braze’s “Export user profile by identifier” endpoint: https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/

Optional: check can be configured to either check the attribute on the first profile in the API Response or if any profile in the response has the matching attribute value.

 

API Calls for Checking Customer Status

Subscription Group Check
GET /subscription/user/status?email[]={{email}} HTTP/1.1
Host: rest.iad-{{instance}}.braze.com

Export User Profile
POST /users/export/ids HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"email_address": "{{email}}"
}

 

4. Checking Mailability

Wunderkind can check a user’s status attribute in a specific subscription group or check a user’s email_subscribe attribute on their profile. Which check to use depends on how the client’s source of truth in Braze in terms of email marketing mailability.

Wunderkind supports both opt-out and opt-in (i.e. no record found is considered unsubscribed) for each type of check.

Subscription Group Check is done using Braze’s “List user’s subscription group status” endpoint: https://www.braze.com/docs/api/endpoints/subscription_groups/get_list_user_subscription_group_status/

  • Can batch up to 200 users per call
  • Can be configured compare the status to either “opt_in” or not “unsubscribed”
  • Can check an “Unsubscribed” subscription group: if a user is not in the subscription group or their status does not equal “subscribed”, they are considered subscribed.

Export User Profile is done using Braze’s “Export user profile by identifier” endpoint: https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/

  • Can be configured compare the email_subscribe attribute to either “opt_in” or not “unsubscribed”

API Calls for Checking Mailability

Subscription Group Check
GET /subscription/status/get?subscription_group_id={{subscription_group}}&email[]={{email}} HTTP/1.1
Host: rest.iad-{{instance}}.braze.com


Export User Profile
POST /users/export/ids HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"email_address": "{{email}}"
}

 

5. Updating Unsubscribe Status

Similar to Checking Mailability, we have two options for how we update a user’s unsubscribe status when they unsubscribe from a Wunderkind email.

Subscription Group Set is done using Braze’s “Update user’s subscription group status” endpoint: https://www.braze.com/docs/api/endpoints/subscription_groups/post_update_user_subscription_group_status/

  • Unlike our mailability check, batching is not supported

Export User Profile Update is done using Braze’s “Export user profile by identifier” endpoint: https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/

  • This approach will make a call to update the subscription_state to unsubscribed
  • If the user does not exist in Braze, we will add a new non-mailable user using the users/track endpoint

API Calls for Updating Unsubscribe Status

Subscription Group Set
POST /subscription/status/set HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"subscription_group_id": "{{subscription_group}}",
"subscription_state": "unsubscribed",
"external_id": "{{email}}",
"email": ["{{email}}"]
}

Unsubscribe Existing User
POST /email/status HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"email": "{{email}}",
"subscription_state": "unsubscribed",
"user_aliases": {
"alias_name": "{{email}}",
"alias_label": "Added Via Wunderkind"
}
}
Unsubscribe New User
POST /users/track HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json


{
    "attributes" : [{
    "_update_existing_only": false,
    "user_alias": {
        "alias_name" : "{{email}}",
"alias_label" : "Added Via Wunderkind"
    },
    "email": "{{email}}",
    "email_subscribe": "unsubscribed"
}]
}

 

6. Sender Options

Wunderkind is able to deploy an email in two ways: either through Wunderkind’s ESP, or through your Braze account (this is called “Client Sender”).

Client Sender

With a Client Sender Integration, Wunderkind will pass a fully-rendered email to Braze for deployment, leveraging Braze’s “Send campaign messages via API-triggered delivery” endpoint: https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns/

Emails are hosted in Wunderkind’s platform and sent through the API with the full html body. Note that we do not support Braze’s dynamic scripting language, Liquid. This means that our emails cannot leverage additional dynamic content hosted by Braze. Additionally, Braze has a 50kb file size limit. Because of this, Wunderkind makes great efforts to minify our code as well as reduce unnecessary email content.

Wunderkind Sender

With the Wunderkind Sender, we’ll deploy Wunderkind emails through our own ESP.

 

API Calls for Client Sender

Triggered Delivery
POST /campaigns/trigger/send HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"campaign_id":"{{campaign_id}}",
"recipients":[
{
"external_user_id":"{{email}}",
"trigger_properties":{
"full_body":"{{html_body}}",
"subject":"{{email_subject}}"
},
"send_to_existing_only":false,
"attributes":{
"email":"{{email}}"
}
}
]
}

 

7. URL Appending

URL Appending is one of Wunderkind’s most impactful identification methods. It allows us to identify users returning to your site from marketing messages (non-WKND marketing emails). It is a reverse lookup that we're able to do using a key (unique identifier) that maps to a plaintext email address and appended to all clickout email links.

Within Braze, please append the braze_id to all email links. We recommend using “bxid” as the URL key (eg, bxid=braze_id), but any URL key name is supported so long as the value appended is the “braze_id”. 

We’ll then perform a lookup using the braze id using the endpoint: https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/

API Calls for URL Appending

API Calls for URL Appending
Export user profile by identifier
POST /users/export/ids HTTP/1.1
Host: rest.iad-{{instance}}.braze.com
Content-Type: application/json

{
"braze_id": "value"
}

 

8. Important Callouts

  • Our Braze Client Sender is limited by Braze’s 50kb file size limit. Because of this, Wunderkind makes great efforts to minify our code as well as reduce unnecessary email content.

 

Related articles

Powered by Zendesk