Email Integration Guide

This guide applies to all Branch Email partners.

Please follow the steps below to integrate your ESP with Branch.

If your ESP requires additional instructions, you will be directed to a dedicated guide.

1. Complete Email prerequisites

Caution
The following Email prerequisite includes providing URI schemes and other components that may require a developer:
Add Deep Link Routing & Required Redirects

Caution
The following Email prerequisites involve app code changes that may require a developer:
Implement the Branch SDK
Enable Universal Linking
Add Your ESP’s CTD to Your Associated Domains Entitlement and verify it is valid using our AASA file Validator
Add Handle Web-Only Content App Code
Add Return YES to continueUserActivity

2. Enable the integration

To enable the integration:

In the left-hand navigation, click Email.
On the Email overview page, click the Manager tab at the top.
Find your ESP and click Enable.

Note
Branch automatically detects any global link settings you have already provided during the initial setup of your Branch account as outlined above.
If you have not set up your global link settings and redirect preferences, you will be prompted to do so at this time.

3. Provide click tracking domain

Click tracking domains allow you to track engagement on email opens and link clicks.

If you're unsure what your click tracking domain (CTD) is, take a look at one of your recently sent emails. If you hover over the link or right-click/copy the link address, you will see that the domain of the link in the email does not match the URL in your HTML. This domain is your click tracking domain used by your ESP to provide you click reporting.

Alternatively, use the button below to find your ESP's documentation on how to find your click tracking domain. If no documentation is available, we provide a link on how to contact the support team for your ESP.

Caution
Leave off http:// and https:// when adding your click tracking domain in the Branch Dashboard.

2412

Caution
Before you click NEXT and proceed to the Validate & Test section, please complete the following step, as it’s required for passing integration validation.

Expand for ESP CTD list

mailgun

mandrill

Important considerations

Please keep in mind that:

You can enable the integration with multiple CTD if needed, but you cannot add the same CTD to multiple Branch dashboards or ESP integrations.
In some ESP integrations, you will also be required to add a "data domain" the ESP uses to collect click data.
- The ESP selected will dictate whether this field appears or not - if the field does not appear, you're not required to add it.
- Confirm the data domain with your ESP’s account manager.
In some ESP integrations, you will also be required to send them the AASA file Branch generates by providing your ESP's contact email.
- The ESP selected will dictate whether this field appears or not - if the field does not appear, you're not required to add it.

4. Point DNS CNAME to Branch

The majority of ESP integrations require updating the DNS record for your CTD to include a CNAME (alias) record that points to Branch’s thirdparty.bnc.lt domain.

Please follow your web hosting provider’s instructions on how to configure your DNS CNAME. Here are a few common provider’s instructions for reference:

Important CNAME info:

The Branch Dashboard must be enabled & reflect the CTD after you add the CNAME.
If the CTD already has SSL setup, confirm if your security credentials allow a 3rd party to submit a CSR on behalf of the domain. If not, contact Branch's Support team, to coordinate providing an SSL certificate manually to Branch.
Once the CNAME is added, Branch auto-generates an SSL certificate and AASA file for your click tracking domain. It may take up to an hour to resolve SSL errors once you change the CNAME. During this time, link redirects on the click tracking domain will redirect to the Default URL you provided in the General Configuration section of your account.
If you are making this change to a live domain with active email click traffic, schedule the CNAME change to occur during an off-hours time with low click traffic.

5. Validate the integration

Once the SSL certificates and AASA file (iOS only) have been generated, you can proceed to reviewing the validation tests, fixing any issues, and then testing the integration.

Branch automatically validates the following:

iOS SDK is integrated (required)
Android SDK is integrated (required)
Deep linking is setup (required)
Click Tracking Domain is setup (required)
AASA file is valid (required) - Use our AASA File Validator: https://branch.io/resources/aasa-validator/
SSL is correctly setup (required)
CNAME points to thirdparty.bnc.lt (case-by-case requirement)
Universal Linking is setup (required)
Hosted deep link data (optional)
App Events being tracked (optional)
Android App Links (optional)

Common validation issues

Below are some possible validation issues you might experience during Branch Email integration.

CNAME does not point to Branch

Pointing your DNS CNAME to Branch is a vital step of the integration process.

Please make sure to do the following:

Log into your DNS provider’s console and add the CNAME record as described here.

Wait at least 60 minutes after you’ve added the CNAME record so that it has time to propagate and Branch can create the resulting SSL certificates and AASA files (for iOS apps only).

SSL not correctly set up

If you are having issues with the SSL certificate validating, the culprit is generally the fact that your click tracking domain already has SSL set up and there are restrictions that prevent a 3rd party from submitting a Certificate Signing Request on your behalf.

AASA file is invalid

The main reason for this error is the fact that it depends on the SSL being set up correctly. By addressing the SSL error, the AASA file error should resolve itself simultaneously.

6. Test the integration

Once the validation process is complete, you can test the integration by generating a test link. The test link generated by Branch is unique in that it’s already converted to a Branch Link for you and allows you to test without creating an email template in your ESP. In reality, this conversion happens behind the scenes once a user clicks on your normal email template link.

To generate a test link:

In the Validate & Test section, input a URL from your website.
Click Get Test Link.
Once the test link is generated, you can share it via:
1. Copy to clipboard
2. SMS
3. Email

Once you’ve generated your test link, click the link on your mobile device.

Tip
Make sure your mobile device already has the app installed!

7. Send emails with flagged links

Before you start setting up your email campaigns, you need to determine what flow you want the user to experience and flag your email link accordingly.

Most ESPs support the following user flows:

Deep linking users to in-app content
- Added to your links as a URL query parameter:
  <a href="links.example.com?$deep_link=true" >Link to your app!</a>
- Added to the HTML:
  <a href="http://example.com" deeplink="true">Link to your app!</a>
Linking users to web-only content
- Added to your links as a URL query parameter:
  <a href="links.example.com?$web_only=true" >Link to your app!</a>

Expand for required link flags for each ESP

ESP Name	ESP required link flags
	Deep linking users to in-app content: add `$deep_link=true` to you links as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	See Dedicated Adobe Campaign Classic Guide
	See Dedicated Adobe Campaign Standard Guide
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` to your links as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` to your links as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content via UI Editor: select the Deep Link checkbox Deep linking users to in-app content via HTML Editor: add `universal="true"` to the HTML ⚠️If you are using dynamic links in email, contact Bluecore team to enable link scraping.⚠️
	Deep linking users to web-only content: add `web-only="true"` to your HTML code
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `universal="true"` to the HTML
	Deep linking users to in-app content: add `data-msys-sublink="uni"` to the HTML
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	See Dedicated Clevertap + Amazon SES Guide
	See Dedicated Clevertap + Mailgun Guide
	See Dedicated Clevertap + Mandrill Guide
	See Dedicated Clevertap + Sendgrid Guide
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true`to your links as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	*Automatic Link Recognition: requires setting up iOS Universal links in your Iterable account.*
	Deep linking users to in-app content: add `kahuna_branch_deep_link=true` as a query parameter
	Deep linking users to in-app content: add `universal="true"` to the HTML
	Deep linking users to in-app content: add `universal="true"` to the HTML
mailgun	Deep linking users to in-app content: add `deeplink="true"` to the HTML
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
mandrill	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter AND add `mobile="true"` to the HTML Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `universal="true"` to the HTML
	Deep linking users to in-app content: add `deeplink="true"` to the HTML
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	See Dedicated Oracle Responsys Guide
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Linking users to web-only content: add `&noapp=true` to your links as a query parameter. *Requires enabling web-only tagging for your Sailthru account.*
	See Dedicated Salesforce Open Web Default Guide
	See Dedicated Salesforce Open App Default Guide
	See Dedicated Salesforce Legacy v2 Guide
	See Dedicated Salesforce Legacy v3 Guide
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `universal="true"` to the HTML
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `universal="true"` to the HTML
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter
	Deep linking users to in-app content: add `$deep_link=true` as a query parameter Linking users to web-only content: add `$web_only=true` to your links as a query parameter

FAQs

What are the use cases for Email?

How to Open Emails in Android to Support `web_only` Use Case

There are 2 options to support the web-only use case in Android to open a Branch Email link:

1. Remove the CTD from the manifest file, this will let all the links coming from the email to open as web_only. In cases where the apps need to open after clicking the branch link, URI scheme would serve that use case.

2. If you want to use applinks and still have the email links open web_only, then add the following code in the Android app to support the web_only logic.

@Override
public void onStart() {
    super.onStart();
    Branch.getInstance().initSession(new Branch.BranchReferralInitListener() {
        @Override
        public void onInitFinished(JSONObject referringParams, BranchError error) {
            if (error == null) {
                //logic to handle webonly routing
                String webOnlyParam = referringParams.optString("$web_only");
                if(!webOnlyParam.isEmpty()) {
                    if(webOnlyParam.contentEquals("true")) {
                        String url = referringParams.optString("$canonical_url");
                        if(!url.isEmpty()) {
                            Intent i = new Intent(Intent.ACTION_VIEW);
                            i.setData(Uri.parse(url));
                            startActivity(i);
                        } else { 
                            Log.i("Tag","missing $canonical_url"); 
                        }
                    }
                } else { 
                    //Logic to handle routing in app 
                }
            }
        }
    }, this.getIntent().getData(), this);
}

Why do all my links redirect to https://branch.io when I add CNAME to them?

Once the CNAME is added, Branch auto-generates an SSL certificate and AASA file for your click tracking domain. It may take up to an hour to resolve SSL errors once you change the CNAME. During this time, link redirects on the click tracking domain will redirect to https://branch.io.

If you are making this change to a live domain with active email click traffic, schedule the CNAME change to occur during off-hours with low click traffic.

What do the Email validation errors/warnings mean and how can I fix them?

Here's the explanation and fix for all the validation errors:

iOS SDK is not integrated: This error is thrown when the Branch SDK has not been integrated into the iOS app.
Fix: You need to set up the iOS SDK as our official documentation.
iOS SDK is integrated but is not the latest version. This may affect email functionality.: This warning is thrown when the Branch SDK version on iOS is lower than the latest version.
Fix: Update the Branch iOS SDK
Android SDK is not integrated: This error is thrown when the Branch SDK has not been integrated into the Android app.
Fix: You need to set up the Android SDK as our official documentation.
Android SDK is integrated but is not the latest version. This may affect email functionality.: This warning is thrown when the Branch SDK version on Android is lower than the latest version.
Fix: Update the Branch Android SDK
Deep linking is not set up for email: The following are all the possible settings you can configure for deep linking with email. To understand each of the settings you can read our documentation here.
Click tracking domain is not set: For Branch links to be generated, you would need to provide the domain of the link that would be used in the email template. To understand how to find your ESP's click tracking domain, you can read our documentation here.
AASA is invalid: If you have not set up the Universal Links in the app, you'll get this error. This is mandatory for Deep Linked Emails to work on iOS.
Fix: You can setup Universal Link by following our documentation here.
CNAME points to thirdparty.bnc.lt: For Branch to host your AASA file and generate SSL certificates on the link domain for the email, you are required to CNAME the domain to thirdparty.bnc.lt. Before making this change, please make sure your setup requires this as some ESP have an option to upload the AASA at their end. Please verify this step in the documentation for your ESP here.
SSL is not correctly set up: Once you setup the email domain on the Branch dashboard and CNAME as per the step 6, we would provide an SSL certificate to host your AASA file over HTTPS. Please contact support@branch.io if you find the SSL certificate is not issued. This step is only required if error 8 is valid for your ESP.
Deep link data is hosted on your website: We recommend using the Hosted Meta Data on the web pages for deep linking. This helps in auto-generating the link data for emails in the Branch links. To learn about hosting metadata for Branch, you can follow our documentation here.
Revenue or custom events are tracked: This is a recommend in-app setup to track the revenue and the custom events which can be attributed to the Branch link generated in the emails.
Universal/App Links are not configured: We strongly recommend setting up the Universal Links for iOS and App Links for Android to launch the app directly from the emails.

Why is there an additional Safelink redirect on top of my Click Tracking Domain?

While testing your Branch Email integration, you may see an additional wrapping around your email links. Platforms like Outlook will add an additional redirect for security purposes.

For example - you might see https://safelinks.protection.outlook.com/ before a 302 Redirect to the Click Tracking Domain.

Fix: Send and open the email to a non-Outlook email address

How can I request a new Universal Email partner?

Have your Email Service Provider (ESP) Account Manager fill out the Branch Partner Profile form.

How can I send additional data to my ESP?

Branch's Branch Email integration will automatically send click tracking analytics to ESPs. Some ESPs have formal data integrations with Branch to send additional data like installs.

Please refer to Branch's Data Integrations Partner List to see if your ESP supports this.

Email Integration Guide

1. Complete Email prerequisites

2. Enable the integration