Email Integration for Developers

This guide covers the technical prerequisites and implementation details for integrating Branch Email. Marketers should refer to our Email integration guide for marketers for dashboard configuration and campaign setup.

Email integration prerequisites

Before your marketing team can configure Branch Email in the dashboard, you must complete the following technical prerequisites in your app and infrastructure.

1. Add deep link routing & required redirects.

2. Implement the Branch SDK.

3. Enable Universal Linking.

4. Add your ESP's CTD to your Associated Domains Entitlement.

   1. Verify it is valid using our AASA file Validator.

5. Add handle web-only content app code.

6. Add return YES to continueUserActivity.

DNS CNAME configuration

The majority of ESP integrations require updating the DNS record for your click tracking domain (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:

• AWS

• GoDaddy

• CloudFlare DNS

Important CNAME information

• 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.

Integration validation

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

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

CNAME does not point to Branch

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

Please make sure to:

Log into your DNS provider's console and add the CNAME record as described above.

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.

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);
}

FAQs