Enabling HTTPS Engagement Tracking on SparkPost

April 13, 2020 Contributors

Overview

SparkPost supports HTTPS engagement tracking for all self-service customers. This article describes how to use a Content Delivery Network (CDN) to enable SSL engagement tracking for your domain. After completing the steps below, your email recipients will see HTTPS links in the email you send. When they visit a tracked link, your CDN will handle the SSL connection, then pass the HTTP request on to SparkPost. SparkPost will record the click event and redirect the recipient to the original URL.

Configuring SSL Certificates

In order for HTTPS engagement tracking to be enabled on SparkPost, our service needs to present a valid certificate that will be trusted by the email recipient’s browser.  SparkPost does not manage certificates for customer engagement tracking domains, as we are not the record owner for our customers’ domains.

As a workaround, you may use a Content Delivery Network (CDN) service, such as CloudFront, Cloudflare or Fastly to manage certificates and keys for any custom engagement tracking domains you configure.  These services forward traffic onwards to SparkPost so that HTTPS tracking can be performed.

How to Create a Secure Tracking Domain on SparkPost

In addition to SSL certificates, link forwarding, and page rules (see the step by step guide below), you will need to create a tracking domain with the tracking domains API using the "secure": true string. Detailed information on this operation can be found in our API documentation here.

How to Switch a Tracking Domain from Insecure to Secure

If you have previously created a tracking domain (whether verified or unverified), and wish to switch it from insecure (the default value for tracking domains) to secure, use the tracking domains API PUT call to update the tracking domain with the "secure": true string. Detailed information on this operation can be found in our API documentation here.

Step by Step Guide with CloudFlare

The following is a sample guide for use with CloudFlare only; please note, the steps to configure your chosen CDN will likely differ from CloudFlare in workflow. Please refer to your CDN’s documentation and contact their respective support departments if you have any questions.

  1. Create CloudFlare account

  2. Go to “DNS” tab on the CloudFlare UI:

  3. Add domain and then add the following Cloudflare NS records (please note, for other providers, the NS records to be used will differ):

    These values can be found under the DNS tab on the Cloudflare UI.

    Example:

    Using the domain track.example.com, below is a command line DIG command to confirm that the NS records have been updated to reflect the required changes:

  4. Create the appropriate page rule settings for the domain. In the page rules tab, perform the following instructions:

    • Page Rule Tab -> Create Page Rule
    • Enter your domain like so: track.yourdomain.com/*
    • Add a Setting -> Forwarding URL (you may need to specify a 301 redirect option)
    • Destination URL is https://<CNAME_VALUE>/$1. Replace <CNAME_VALUE> with the value displayed in the tracking domains section of the SparkPost UI. E.g.: for SparkPost US, this would be spgo.io; for SparkPost EU, this would be eu.spgo.io; for PMTA+Signals, refer to your user guide.
    • Save and Deploy (turn page rule on)

  5. Cloudflare has Universal SSL for all accounts, but it’s good to ensure that setting on the page rule is "SSL". This is required for how CloudFlare will validate the certificate on the origin.

    More information on SSL options for Cloudflare can be found here.

  6. Turn the page rule ON.

  7. Add a CNAME entry into DNS for your tracking domain. The value in the record doesn’t matter; the record simply needs to exist. For example, if your tracking domain is track.example.com, a CNAME value of example.com is sufficient. Without a record to reference, the the page rule never gets triggered, and the proper redirection will not occur. Please note that the typical time to progagation of new CNAME records is often around five to ten minutes, but can be longer depending on your DNS provider.

  8. Run the Update a Tracking Domain API using the following Post Data:

Note: If you would like this tracking domain to be the default, please add "default": true to the JSON object above, before updating the domain.

  1. Navigate to the Tracking Domains section in the UI and click the orange "test" verification link. At this point, the process is complete.

Step by Step Guide with AWS CloudFront

The following is a sample guide for use with AWS CloudFront only; please note, the steps to configure your chosen CDN will likely differ from CloudFront in workflow. Please refer to your CDN’s documentation and contact their respective support departments if you have any questions.
For up to date information on creating a distribution via CloudFront, please refer to the AWS docs

  1. Login with your credentials onto AWS console and navigate to CloudFront.

  2. Choose Create Distribution:

  3. On the "Select a delivery method for your content" page, under the Web section, choose Get Started.

  4. On the Create Distribution page fill out the following:

    • Under Origin Settings, fill in the Origin Domain Name. Use the value displayed in the tracking domains section of the SparkPost UI. E.g.: for SparkPost US, this would be spgo.io; for SparkPost EU, this would be eu.spgo.io.

    • Under Origin Settings, for Origin Protocol Policy, select HTTPS Only.

    • Under Distribution Settings, fill in Alternate Domain Names (CNAMEs) with your custom tracking domains (i.e., www.customtrackingdomain.com).

      • Note: Can add up to 100 domains.

    • Under Default Cache Behavior Settings, set Query String Forwarding and Caching to "Forward all, cache based on all".

    • Create, or update, a CNAME record with your DNS service to route queries for tracking domain(s) with your CloudFront distribution ID.

    • Under Distribution Settings, for "SSL Certificate", select Custom SSL Certificate – Upload certificates as needed.

    • At the bottom of the page, press Create Distribution.

  5. On the Create Distribution page, under Default Cache Behavior Settings, it is recommended to set a custom whitelist for the User-Agent header. Set the configuration Cache Based on Selected Request Headers to "Whitelist". At this point you will need to "Add Custom" for User-Agent. This allows User-Agent data to be present in your engagement events received from SparkPost.

  6. Log into SparkPost app use the SparkPost Tracking Domain API.

  7. Add custom tracking domain and verify the domain.

  8. Use tracking domain while sending messages.

Updating an Existing Domain on AWS CloudFront

If you use AWS CloudFront to enable SSL engagement tracking, by default, CloudFront replaces the User-Agent header with "Amazon CloudFront," obscuring device and client information. To regain the device and client information, configure CloudFront to forward the original User-Agent header.

  1. Navigate to the CloudFront console.

  2. Click on your distribution’s ID.

  3. Click on the "Behaviors" tab.

  4. Click on the checkmark next to the first item in the list.

  5. Click on the "Edit" button.

  6. In the dropdown next to "Cache Based on Selected Request Headers," select "All."

  7. At the bottom of the page, click on the "Yes, Edit" button.

Step by Step Guide with Fastly

Sign up for Fastly or log in to an existing account.

  1. Click Configure on the Dashboard.
  2. Click the gear icon to open the Manage Service menu and click Create.

Set the options as follows:

Server address and port: For SparkPost US, this would be spgo.io : 443; for SparkPost EU, this would be eu.spgo.io : 443
Domain: Your click tracking domain, e.g. click.business.com
Description: SparkPost (or whatever you like!)