To send email with Iterable, you'll need to set up senders, sending domains, and tracking domains. These things determine the sender of your messages and the domains Iterable can use for link rewriting and click tracking.
To configure which email links Iterable should rewrite as deep links (so they open in your mobile app, if a contact has it installed), you'll need to configure destination domains and paths (by setting up an apple-app-site-association file).
Additionally, you can use your tracking domains to shorten the links you include in SMS campaigns.
This guide describes these concepts in more detail.
Table of contents
Overview
The following few sections describe how Iterable works with email service providers, sending domains, senders, tracking domains, deep links, destination domains, apple-app-site-association files, and assetlinks.json files.
Email service providers (ESPs)
By default, Iterable projects send email using Amazon SES with a shared IP address. However, it's also possible to use other ESPs (for example, Sparkpost or SendGrid).
TIP
To use an ESP other than Amazon SES, work with your Iterable customer success manager.
Definitions
This guide describes the following things:
-
Sending Domains - The domains from which your Iterable project can send email.
When using Amazon SES with a shared IP address, a project can have only one sending domain, defined on the Settings > Project Settings screen or based on the web site associated with your Iterable organization.
For other ESP configurations, you can define multiple sending domains on the Settings > Domains page.
-
Senders - Verified email addresses from which your Iterable project can send email.
When using Amazon SES with a shared IP address, each sender should align with the sending domain defined in your Iterable project's settings or the web site associated with your Iterable organization—whichever defines your sending domain.
For other ESP configurations, each sender should align with one of the sending domains defined on the Settings > Mail page.
-
Tracking Domains - The domains Iterable can use to rewrite links for email campaigns and shorten links for SMS campaigns. Tracking domains must be aliased (via a DNS record) to
links.iterable.com
, which handles click tracking (and helps with attribution). Also called link tracking domains.Generally, a tracking domain should align with your sending domain. For example, a project with a sending domain of
example.com
might use link tracking domainlinks.example.com
.TIP
When using a tracking domain to shorten links for SMS campaigns, you might want to use a short domain (to save characters). For
example.com
, this might be something likeexmpl.io
.For example, for a message that includes an email with a link to
https://example.com/products/123
, contacts will see the link rewritten as something likehttps://links.example.com/u/click?_t=7dd208...
. After a contact clicks a link (whether in email or SMS), the tracking domain tracks the click and redirects to the original link destination.In email, a link's rewritten URL can be seen when readers click on, hover over, or copy the link. Because of this, it's a good idea to clearly associate the tracking domain with the email's sending domain (so that the link looks trustworthy).
-
Deep Links - Links that open (when tapped on a mobile device) directly in your app, if it's installed—and a web browser otherwise.
Iterable rewrites standard links and deep links to point to your link tracking domain. Rewritten URLs for standard links include
/u/
and rewritten URLs for deep links include/a/
. Your mobile apps can be configued to expect these/a/
links (as associated with your particular link tracking domains), and to open them without a browser.IMPORTANT
- To use Iterable to send deep links, you must set up a custom, HTTPS-enabled tracking domain.
- Iterable's SMS link shortening feature does not yet support deep links.
Destination Domains - For a particular tracking domain, create destination domains to specify which links Iterable should rewrite as deep links. Then provide an apple-app-site-association file to describe the specific paths that should be rewritten for each destination domain. For more information, see below.
How do the pieces fit together?
Iterable senders, sending domains, tracking domains, and destination domains are related.
For email campaigns:
You'll select one of your project's senders.
Iterable uses the selected sender to determine the campaign's sending domain.
-
Each sending domain is associated with a single tracking domain. Iterable uses that tracking domain to rewrite your campaign's links, and then tracks those links when they're clicked.
Additionally, the linking tracking domain can set attribution cookies in the recipient's browser. These cookies can help your server understand which campaign and template caused the click, and you can use this information to attribute a purchase or conversion event to a specific campaign.
For email campaigns, the selected tracking domain also determines which email links Iterable will rewrite as deep links. The destination domains defined for a particular tracking domain determine the domains for which Iterable will rewrite links as deep links. The apple-app-site-association file for each destination domain defines the relevant paths.
For SMS campaigns:
When editing the campaign's template, you'll select a tracking domain to use for URL shortening (preferably a custom domain, but you can also use
itbl.co
).Iterable uses the selected domain to shorten your campaign's links. When your contacts receive your campaign, they'll see links that look something like
https://itbldocs.site/2NMwZ
(assuming, in this case, a tracking domain ofitbldocs.site
).Any Iterable project can use the
itbl.co
tracking domain for SMS link shortening. Because of this, the resulting URLs have a few extra characters to map your links to your project. For example, a link shortened withitbl.co
might look something likehttps://itbl.co/KT~2NMwz
, whereKT~
is used to map the link back to your project.
IMPORTANT
Iterable saves shortened SMS links for a minimum of 30 days. If a user clicks an expired, shortened link, they'll see a friendly 404 message.
Permissions
To work with the items described in this guide, you'll need the Channel Configuration > View (to view) or Channel Configuration > Manage (to edit) permission.
Email: setting up your project's ESP
The following sections describe how to set up your ESP, whether Amazon SES with a shared IP (the default) or another ESP.
Amazon SES with a shared IP address (default configuration)
If you're using Amazon SES with a shared IP address (Iterable's default ESP configuration), follow these instructions to configure your project to send email:
-
Specify your project's sending domain. When using Amazon SES with a shared IP address, an Iterable project can only have one sending domain. To specify it, navigate to Settings > Project Settings and enter it in the Custom Project Sending Domain input.
NOTES
- If you don't provide a Custom Project Sending Domain, Iterable uses the domain associated with your organization's configured web site.
- When using Amazon SES with a shared IP address, there's no need to specify a sending domain on the Settings > Domains screen.
-
To enable your sending and link tracking domain, configure your site's DNS. To do this, navigate to Settings > DNS Setup, copy the DNS records and work with your site administrator to add them to your site's configuration.
IMPORTANT
The DNS records shown on the Settings > DNS Setup screen are valid only when using Amazon SES with a shared IP address. When using other ESPs, ignore this screen.
-
Add senders to your project, each of which should have a domain that matches the sending domain defined in step 1, above. To do this, navigate to Settings > Senders, click Create New Sender and specify their information.
If you've configured your DNS (as described in the previous step), Iterable should display the new sender as Verified. Otherwise, Amazon will send you a verification email for new senders. After you respond, Iterable will mark the sender as verified.
-
Create a custom tracking domain that Iterable can use to rewrite links in the emails your project sends. For more information, read this guide's Overview.
TIP
If you don't want to use a custom tracking domain, you can skip this step, and Iterable will rewrite links in email campaigns as
http://links.iterable.com/...
. Remember, however, that this URL is visible to your recipients when they click on, hover over, or copy a link. They won't expect to see aniterable.com
URL, so it's best to provide a custom tracking domain.To do this:
Navigate to Settings > Domains and click New Tracking Domain.
For the tracking domain, enter a domain such as
links.<YOUR_SENDING_DOMAIN>
. For example, if your sending domain isexample.com
, your tracking domain might belinks.example.com
(which matches the CNAME record configured for your site's DNS in step 2, above).To set the new tracking domain as your project's default, click the down on its table row and choose Set as Default.
If your website is HSTS compliant, or if you will be sending deep links that should be opened by a mobile app, enable HTTPS for your tracking domain. After you do this, click your tracking domain's Edit button and turn on the Enable HTTPS toggle.
Allow 24 hours for Iterable to verify the tracking domain.
Other ESPs (Sparkpost, Sendgrid, etc.)
If you'd like to use an ESP other than Amazon SES with a shared IP address, work with your customer success manager to configure your ESP and your Iterable project.
You'll need to set up:
Your ESP configuration.
-
Your site's DNS. In particular, your DNS will need to map custom link tracking domains (for example,
links.example.com
) tolinks.iterable.com
(Iterable's server that actually performs the click tracking and redirection).IMPORTANT
The DNS records shown on the Settings > DNS Setup screen are valid only when using Amazon SES with a shared IP address. When using other ESPs, ignore this screen.
Tracking domains (on the Settings > Domains screen). Set up HTTPS for these tracking domains as necessary (mandatory if you need to send deep links).
Senders (on Iterable's Settings > Senders screen).
Sending domains (on the Settings > Domains screen). Make sure to verify the domain and select a tracking domain.
SMS: Setting up a link shortening domain
To create a new link tracking domain specifically for SMS link shortening:
- Register the domain.
- It's a best practice to enable HTTPS for all tracking domains. To do this, use a service such as Amazon CloudFront or Cloudflare.
- In the domain's DNS, set up a CNAME record, aliasing it to
links.iterable.com
. - In Iterable, navigate to Settings > Domains and add this new domain as a link tracking domain, making sure to enable HTTPS.
- Once Iterable has verified the domain, you can use it for SMS link shortening.
IMPORTANT
Before using a new tracking domain in a live campaign, send an internal test campaign to make sure that it works as expected.
Deep links
Deep links, when tapped on a mobile device, open directly in your mobile app if it's installed, and in a web browser otherwise.
To set up your Iterable project to send deep links, follow these steps:
IMPORTANT
- Iterable's SMS link shortening feature does not yet support deep links.
- If your project used deep links before Iterable released deep link configuration enhancements on July 30, 2020, your existing configuration will continue to work. However, read the migration instructions for more information.
1. Set up a custom tracking domain and enable HTTPS
To enable deep linking, you'll need an HTTPS-enabled custom link tracking domain,
rather than Iterable's default link tracking domain (http://links.iterable.com
).
There are a few reasons for this:
Apple requires that iOS apps pull apple-app-site-association files from an HTTPS-enabled endpoint, without redirects. Since Iterable hosts this file for your app, (as configured by your site's DNS), you'll need to enable HTTPS.
Android requires that assetlinks.json files are served with HTTPS. Since Iterable hosts this file for your app, (as configured by your site's DNS), you'll need to enable HTTPS.
Iterable hosts each tracking domain's aggregate apple-app-site-association file at
https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association
, and assetlinks.json file athttps://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json
. It is not possible for Iterable's default tracking domain (http://links.iterable.com
) to host these files for all the various Iterable projects that use it as a tracking domain.
2. Decide which links your mobile apps should open
Determine the precise link patterns your mobile app should open. Once you've made this decision, build apple-app-site-association and assetlinks.json files (if you don't already have them).
IMPORTANT
Even if you don't have an iOS app, you'll need to create an apple-app-site-association file. Iterable uses this file to determine the paths to rewrite as deep links.
For more information, see Iterable's iOS Universal Links and Android App Links guides
3. Configure your mobile apps to support deep links
To enable deep links in your mobile apps, follow these instructions:
- Configure your iOS app to support Universal Links (the iOS implementation of deep links).
- Configure your Android App to support App Links (the Android imlementation of deep links).
4. Set up destination domains and paths in Iterable
Destination domains and their paths make it possible to specify that an app should open some links—but not others—for a particular tracking domain.
For each of your tracking domains, you can define multiple destination domains. Iterable uses these destination domains, along with the the paths listed in their associated apple-app-site-association files, to determine which links to rewrite as deep links.
For example, consider a project that has the following setup:
- A
links.example.com
tracking domain - A
support.example.com
destination domain for that tracking domain - An associated apple-app-site-association file that specifies
/product/*
as a path
Now, assume that this project sends an email that contains a link to
https://support.example.com/product/widget
, from a sender whose sending
domain is associated with the links.example.com
tracking domain mentioned
above.
Since this link URL matches the destination domain (support.example.com
)
and path (/product/widget
matches /product/*
), Iterable will rewrite the link
as a deep link before sending it.
NOTE
The deep link will look something like https://links.example.com/a/click?_t=7dd2086...
.
The /a/
denotes that it's a deep link.
On the other hand, a link to https://support.example.com/news/today
will not
be rewritten as a deep link. The destination domain matches the URL, but the
apple-app-site-association file has no match for the path.
IMPORTANT
Remember:
- The sender you select for an email campaign determines its sending domain.
- The sending domain determines the tracking domain.
- The tracking domain has a set of destination domains.
- Each destination domain has an apple-app-site-association file, which specifies URL patterns your app can handle for that destination domain.
Because of this, the sender you select for an email campaign ultimately determines which links Iterable rewrites as deep links.
To set up destination domains and their paths:
Navigate to Settings > Domains.
-
On the tracking domain you'd like to configure, click Edit.
-
On the Tracking Domain screen, click New Destination Domain.
Specify the destination domain for which you'd like your app to open at least some links, and click Create.
The destination domain will now be listed in the table. To modify it, click its Edit button.
-
On the Destination Domain screen, use the Edit Configuration buttons to upload the apple-app-site-association and assetlinks.json files you created above. After uploading the files, click Save Changes in each section.
IMPORTANT
- Each tracking domain has a single assetlinks.json file. Uploading an assetlinks.json file for any of that tracking domain's destination domains overwrites it for all of that tracking domain's destination domains.
- Upload standard apple-app-site-association files. Iterable previously
required apple-app-site-association files that contained an
iterable
section, and which explicitly called out the/a/
path which Iterable uses to denote deep links. However, this is no longer required. The legacy file format still works, but will cause Iterable to rewrite links that contain/a/
as deep links. - To enable or disable a particular destination domain for a tracking domain, navigate to the Tracking Domain screen for the tracking domain in question, click the down arrow next to the destination domain in question, and choose Enable or Disable.
5. Test your deep link configuration
To test your deep link configuration, follow these steps:
Check to make sure that Iterable exposes your tracking domain's aggregate apple-app-site-association file at
https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association
. This file is a combination of all the apple-app-site-association files uploaded to destination domains associated with the relevant tracking domain.Check to make sure that Iterable exposes your assetlinks.json file at
https://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json
.-
Send an email campaign to yourself, from a sender who's ultimately associated with the tracking domain to which you just added a destination domain.
In the email, include test links—some that should be rewritten as normal links (which include
/u/
after Iterable rewrites them), and some that should be rewritten as deep links (which include/a/
after Iterable rewrites them). When you receive the message, inspect the link URLs to make sure that they've been rewritten as you expect.
Test opening these same links in your mobile app, to ensure that the app responds as you expect.
TIP
To verify that your tracking domain's destination domains are enabled, navigate to Settings > Domains, open the tracking domain in question, and make sure the table of destination domains lists them as Enabled. If not, use the drop-down menu (indicated by a down arrow) to enable or disable them.
Troubleshooting deep links
If your deep links open in a web browser instead of your mobile app, make sure that:
- You've enabled HTTPS for your tracking domain.
- Your apple-app-site-association file is properly formatted.
- Your mobile app is configured to use deep linking, as described in iOS Universal Links and Android App Links.
If your deep link open your app, but to the wrong content, review:
- The URL handling methods in your app's code (iOS, Android).
- The contents of your apple-app-site-association file.
Deep link configuration enhancements: migration instructions
The deep linking configuration enhancements release introduced various changes to the configuration of deep links in Iterable. These changes make it possible to:
Define the specific domains and paths that Iterable will (and will not) rewrite as deep links for a given tracking domain (by defining destination domains and giving each one an apple-app-site-association file). This allows you to decide on the subdomains for which a tracking domain should rewrite links as deep links.
Upload and manage apple-app-site-association and assetlinks.json files directly in Iterable, without contacting your customer success manager.
IMPORTANT
If your Iterable project already used deep links prior to the release, your existing configuration will continue to work as expected. However, to take advantage of the new enhancements, you'll need to modify your project's configuration.
Before the configuration enhancements release
Before the configuration enhancements release, for projects with deep links enabled, the tracking domain associated with an email campaign's sender caused Iterable to rewrite as deep links all links that shared a root domain with that tracking domain.
For example, a tracking domain of links.example.com
caused Iterable to rewrite
links to support.example.com
, docs.example.com
and app.example.com
all
as deep links.
After the configuration enhancements release
After the configuration enhancments release, this same behavior remains in effect for tracking domains already configured to send deep links. On the Settings > Domains screen, Iterable marks these tracking domains as Legacy, and they continue to rewrite deep links for all links that point to the tracking domain's root domain, using your existing apple-app-site-association file.
However, once you manually add a new destination domain to a legacy tracking domain, Iterable no longer respects the original configuration. At that point, you'll need to define a destination domain for each domain or subdomain for which you'd like Iterable to rewrite deep links, and upload an apple-app-site-association file for each (to define the specific paths for that domain or subdomain for which links should be rewritten as deep links).
For example, to configure tracking domain links.example.com
to rewrite deep
links for in-email links that point to support.example.com
, docs.example.com
or app.example.com
, you'll need to add three destination domains to that
tracking domain.
NOTE
For any tracking domain, you can enable either your legacy destination domain (which rewrites all links that share the tracking domain's root domain), or you can enable any subset of its new destination domains. You cannot enable both at the same time.
Viewing deep link files
The configuration enhancements release removes the the apple-app-site-association and assetlinks.json files from the Settings > Project Settings screen. To view the Iterable-hosted versions of these files, navigate to:
https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association
https://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json
Further reading
- HTTPS for Click Tracking
- Iterable's Deep Links guides
- Apple's Universal Links documentation
- Android's App Links documentation
Comments
0 comments
Please sign in to leave a comment.