Overview

Connect Braze and SparkPost to Branch so the links in your Braze emails open your app with full tracking and attribution. Branch hosts your SparkPost click tracking domain (CTD), so a tracked link becomes a Branch Link when a user selects it.

Warning: Every tracked link opens your app

SparkPost rewrites every http:// and https:// link in your email to your CTD, including footer links such as unsubscribe, privacy policy, and terms of service. When you add the CTD to your app's Associated Domains, iOS opens your app for every one of those links before the request reaches Branch. Android App Links work the same way once Branch hosts your assetlinks.json file. Branch can't send a link to the browser on its own, because the operating system never sends the click to Branch.

Before you send to customers, handle every link that has no screen in your app. Either add the $web_only=true flag and make sure your app handles it, or exclude the link from click tracking. Otherwise, those links fail for every user who has your app installed. See Route web-only links.

How it works

1. A user selects a link in an email from a mobile mail client such as Gmail or Apple Mail.
2. If the user has your app installed, the operating system opens your app. Branch routes the user to the matching in-app content, such as a product detail page or category page.
3. If the user doesn't have your app installed, Branch routes the user to the web URL in their default mobile browser.
4. If you flag a link as web-only your app opens the web URL in the browser. Your app must include the web-only handler for this to work.

Before you begin

Required roles

Branch Email requires the following roles to enable:

• Developers
• CRM/Email Team
• Braze Account Manager / Support Team

To enable Braze + SparkPost, you first need to:

1. Have admin access to Branch.

2. Have Branch's Engagement product enabled for your Branch account.

3. Implement the Branch SDK into your mobile app (iOS | Android).

   • Set up deep link routing. How your mobile app routes to in-app content determines how you create and tag your Branch Links.

     • Build custom routing inside the routing callback
     • Let Branch use your existing deep link routing

   • Track events.

4. Add the web-only link handler to your app (iOS | Android). You need this step if your emails contain any link that doesn't have a screen in your app.

5. Obtain or set up your Braze click tracking domain (CTD). Contact your Braze account manager for help.

6. Review the Email Overview and Basic Email Integration Guide to understand the feature and our integrations.

Connect Braze + SparkPost in Branch

In Branch, navigate to Email > Manager, find Braze Sparkpost, and select Enable.

Input click tracking domain

Click tracking domains let you track engagement on email opens and link selections. The Braze + SparkPost integration requires you provide the click tracking domain. This is the domain you use with Braze + SparkPost for links in emails.

For additional help, see SparkPost's documentation.

Important click tracking domain rules

• Remove https:// when adding your click tracking domain.
• Never add the same CTD to both your Live and Test Branch environments.
• You can enable the integration with multiple CTDs, if needed, but you can't add the same CTD to multiple Branch instances or email service provider (ESP) integrations.

SparkPost proxy domain

The Braze + SparkPost integration includes an optional SparkPost Proxy Domain field. This is the domain SparkPost uses to proxy click tracking requests. This field may appear blank in Branch. If you leave it blank, Branch applies a default proxy domain behind the scenes, so your integration continues to work as expected. If SparkPost has provided you with a specific proxy domain (such as eu.spgo.io for accounts in Europe, the Middle East, and Africa), enter it in this field. If you're unsure which proxy domain to use, contact your SparkPost account team for confirmation.

Configure your app

Add your Braze + SparkPost CTD to your associated domains

For your iOS app, add the CTD to the Associated Domains. Find additional details in the iOS basic integration guide.

Once the CTD is an associated domain, iOS opens your app for every link on that domain, not only the links you intend to deep link. Important: before you ship your app, complete the steps to Handle web-only links in your app.

Return YES to continueUserActivity

Add the CTD to your iOS app's Info.plist file. Find additional details in the iOS advanced features guide.

Handle web-only links in your app

When a user who has your app installed selects a web-only link, the operating system opens your app. The Branch SDK then returns the link data to your deep link handler. The Branch SDK doesn't open the URL for you: it doesn't show any UI, open a WebView, or launch a browser. Your app must check for the $web_only parameter and open the original URL itself, either in the system browser or in an in-app browser such as SFSafariViewController on iOS or Chrome Custom Tabs on Android.

Deep link handler

If you don't add a deep link handler, links for pages like unsubscribe, privacy policy, and other web-only links open your app and go nowhere.

• iOS: Add the handler from Handle deep links for web-only content. The handler checks the link parameters for $3p and $web_only, then opens the URL in $original_url with the system browser.
• Android: Add the handler from How to open emails in Android to support web-only use case. The handler checks for $web_only and opens the URL in $canonical_url with an intent.

Point DNS CNAME to Branch

Follow your web hosting provider's instructions to configure your DNS CNAME.

Here are a few common providers' instructions for reference:

• AWS
• GoDaddy
• CloudFlare DNS

Update the DNS CNAME and point it to thirdparty.bnc.lt. Once you add the CNAME record, wait up to an hour for Branch to generate SSL and Apple App Site Association (AASA) files for your click tracking domain.

Important CNAME info

• Enable the integration in Branch and add the CTD before you add the CNAME.
• If the CTD already has SSL set up, confirm your security credentials let a third party submit a certificate signing request (CSR) on behalf of the domain. If not, contact Branch Support to coordinate providing an SSL certificate manually.
• Once you add the CNAME, Branch automatically generates an SSL certificate and AASA file for your click tracking domain. It may take up to an hour to resolve SSL errors. During this time, link redirects on the click tracking domain redirect to the Default URL you provided in General Configuration.
• If you are making this change to a live domain with active email click traffic, schedule the CNAME change during off-hours with low click traffic.

Add Branch Links to your emails

Before you send a campaign, decide what each link in the email does and flag it accordingly. You don't need to tag every link. Tracked links open your app by default, so only links that must open a web page need a flag. Every link falls into one of three groups:

Link type	Examples	What to do
Opens a screen in your app	Product page, category page, account page	No flag required to open the app. Add $deep_link=true as a query parameter so Branch converts the link to a Branch Link with deep link data and attribution.
Opens a web page, with click tracking	Promotion landing page, blog post	Add $web_only=true as a query parameter. Requires the web-only handler in your app.
Opens a web page, no click tracking	Unsubscribe, privacy policy, terms of service, links whose URL Braze generates	Add data-msys-clicktrack="0" to the anchor tag so SparkPost leaves the link alone.

Add deep linking flag

For the email links that you want to deep link to content, add $deep_link=true to the URL as a query parameter:

<a href="https://www.example.com/products/123?$deep_link=true">Link to your app!</a>

This converts your links to Branch Links that open the app on iOS and Android, with full tracking and attribution. Tracked links open your app whether or not you add this flag. The flag tells Branch to convert the link, so your app receives deep link data and Branch attributes the click.

Route web-only links

All tracked email links open the app on devices that have it installed. To route a link to the web instead, add $web_only=true to the URL as a query parameter:

<a href="https://www.example.com/promo?$web_only=true">Read more on our site</a>

When a user selects this link, your app opens, reads the $web_only flag, and opens the web URL in the browser. The handler in Handle web-only links in your app does this for you. Braze and SparkPost still record the click, and Branch still attributes it.

Use this flag for links that benefit from click tracking and attribution but don't have a screen in your app.

Exclude a link from click tracking

SparkPost doesn't rewrite a link that carries the data-msys-clicktrack="0" attribute. The href stays on your own domain, so the link opens in the browser on every device and never touches your CTD or your app. Braze, SparkPost, and Branch don't record engagement on it.

<a href="https://www.example.com/privacy" data-msys-clicktrack="0">Privacy policy</a>
<a href="{{${set_user_to_unsubscribed_url}}}" data-msys-clicktrack="0">Unsubscribe</a>

Use this attribute for:

• Footer links that must work on every device and don't need click tracking, such as unsubscribe, privacy policy, and terms of service.
• Links whose URL Braze generates with Liquid, such as the unsubscribe URL, where you can't reliably append a query parameter.

Braze passes SparkPost link attributes through in your email HTML. In the Braze drag-and-drop editor, add the attribute in the link's Attributes section as an anchor tag. For details, see Braze's documentation on Universal Links and App Links and SparkPost's Using Mobile Universal and App Links with SparkPost.

Keep click tracking without opening the app

If a web-only link needs click tracking but must never open your app, use a SparkPost custom sub-path and ask Branch to exclude that path from the AASA file on your CTD.

1. Add data-msys-sublink="web" to the anchor tag of each link that must open in the browser. SparkPost rewrites the link to https://<your CTD>/f/web/... instead of the default /f/a/... path.
2. Contact Branch Support and ask us to exclude /f/web/* from the AASA file on your CTD. Include your CTD and the sub-path you chose.
3. After Branch confirms the change, test the link on a device that has your app installed. It opens in the browser, and Braze and SparkPost still record the click.

Branch makes this change on request for a business need, and it applies only to the sub-path you specify. Links that don't carry the sub-path keep opening your app.

If most of the links in your emails are web-only, ask for the reverse instead. We configure the AASA file so that only links with a sub-path such as data-msys-sublink="app" open your app, while every other tracked link opens in the browser.

Tag email campaigns for analytics

To view email campaign performance in Branch, tag your email links with the ~campaign tag. If your team uses UTM tags, Branch also ingests utm_campaign. This helps remove duplicate counts and surface downstream events. You can add the campaign tag in any comparisons and filters across dashboard views.

Test your links

Test with a device that has your app installed, because this is the case where web-only links fail if they aren't flagged.

1. Send a test email that includes your standard footer to a device that has your app installed.
2. Select a deep link. Your app opens to the matching content.
3. Select the unsubscribe link and each other footer link. Each one opens in the browser.
4. Repeat steps 2 and 3 on a device that doesn't have your app installed. Every link opens in the browser.