Tracking Domains

Tracking domains are used in engagement tracking to report email opens and link clicks. They wrap the open pixel and all links in your emails. When clicked, these links report the event to SparkPost, then quickly forward to the intended destination. By default, the tracking domain on your account is spgo.io (eu.spgo.io for EU accounts). This API allows you to set up and manage custom tracking domains. You can also set one up from your account (EU).

As an example, say your email contains this link:

<a href="https://www.heml.io">Build responsive emails</a>

In order to track clicks on that link, we wrap it. The resulting HTML would look something like this:

<a href="http://spgo.io/e/nInKCLCf9wnO2brop7RTsg...">Build responsive emails</a>

With a custom tracking domain you can replace the domain part of the link. So if your tracking domain was click.heml.io, your HTML would look like this:

<a href="http://click.heml.io/e/nInKCLCf9wnO2brop7RTsg...">Build responsive emails</a>

Association to Sending Domains and Defaults

In order for a tracking domain to be used, it must be associated to a sending domain or set as a default. Once that is done, templates and transmissions that have open or click tracking on will automatically use the domain to wrap links. If a tracking domain is set as default, it will automatically be used with sending domains that aren't associated with a different tracking domain. Default tracking domains do not override associated tracking domains. You can set a default for each subaccount as well. SparkPost picks the first tracking domain it can find to use in this order: 1. Associated tracking domain. 2. Subaccount default. 3. Account default.

DNS

Tracking domains need to be verified via DNS. You'll need to add a CNAME record with the value of spgo.io (eu.spgo.io for EU accounts) to the domain's DNS settings before it can be used or set as the default. For more information and Enterprise settings go here.

Security

Tracking domains use HTTP by default. Using HTTPS requires the set up and management of SSL Certificates, for more information see this guide.

Subaccounts

Tracking domains can only be assigned to subaccounts on creation. They cannot be re-assigned at a later point. If assigned and verified, a tracking domain can also be set as the default for that subaccount. In order to be associated to a subaccount's sending domain, a tracking domain has to be assigned to the same subaccount.

Tracking Domain Object

Example

{
  "domain": "example.domain.com",
  "port": 443,
  "secure": true,
  "default": false,
  "status": {
    "verified": false,
    "cname_status": "pending",
    "compliance_status": "pending"
  }
}

Request Body

domain string

Name of the tracking domain.

port number

The port used when constructing the tracking URL. 80 if secure is false, 443 if secure is true.

secure boolean, default is false

Whether the tracking URL should use HTTPS. HTTP will be used if false.

default boolean, default is false

Whether the tracking domain should be used when not explicitly associated with a sending domain. Only one default domain per account and subaccount can be set. The domain has to be verified to be set as the default.

status object

Contains status details like verification and DNS.

subaccount_id number

ID of the subaccount the tracking domain is assigned to. Not returned unless set and can only be set on creation.

Request

POST /api/v1/tracking-domains

{
  "domain": "example.domain.com",
  "secure": true
}

Response

{
  "results": {
    "domain": "example.domain.com"
  }
}

{
  "errors": [
    {
      "param": "domain",
      "message": "domain is on a DNS blacklist",
      "value": "baddomain.com"
    }
  ]
}

{
  "errors": [
    {
      "message": "The tracking domain already exists"
    }
  ]
}

{
  "errors": [
    {
      "param": "domain",
      "message": "domain must be valid",
      "value": "baddomain"
    }
  ]
}

Create a Tracking Domain

POST/api/v1/tracking-domains

Request Body

domain string required

Name of the tracking domain.

secure boolean, default is false

Whether the tracking URL should use HTTPS. HTTP will be used if false.

Request

POST /api/v1/tracking-domains//verify

Response

{
  "results": {
    "verified": true,
    "cname_status": "",
    "compliance_status": "valid"
  }
}

  {
      "errors": [
          {
              "message": "HTTP request to https://example.domain.com:443 failed.  Please verify that your redirect is functioning and that your SSL certificate is valid.",
          }
      ]
  }

{
  "errors": [
    {
      "message": "resource not found"
    }
  ]
}

Verify a Tracking Domain

POST/api/v1/tracking-domains/{domain}/verify

Parameters

domain string required

Initiate a check against the configured redirect for the specified tracking domain. The domain's status object is returned on success.

Request

GET /api/v1/tracking-domains/

Response

{
  "results": {
    "port": 443,
    "domain": "example.domain.com",
    "secure": true,
    "default": true,
    "status": {
      "verified": false,
      "cname_status": "pending",
      "compliance_status": "pending"
    }
  }
}

{
  "errors": [
    {
      "param": "domain",
      "message": "domain must be valid",
      "value": "baddomain"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource not found"
    }
  ]
}

Retrieve a Tracking Domain

GET/api/v1/tracking-domains/{domain}

Parameters

domain string required

Retrieve an existing tracking domain.

Request

PUT /api/v1/tracking-domains/

{
  "secure": true,
  "default": true
}

Response

{
  "results": {
    "domain": "example.domain.com"
  }
}

{
  "errors": [
    {
      "param": "domain",
      "message": "domain must be valid",
      "value": "baddomain"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource not found"
    }
  ]
}

{
  "errors": [
    {
      "message": "Tracking domain 'example.domain.com' unverified."
    }
  ]
}

Update a Tracking Domain

PUT/api/v1/tracking-domains/{domain}

Parameters

domain string required

Update the attributes of an existing tracking domain. The primary account and each subaccount can only have one default tracking domain. Setting a new default automatically unsets the current relevant default, if it exists.

Request Body

secure boolean

Whether the tracking URL should use HTTPS. HTTP will be used if false.

default boolean

Whether the tracking domain should be used when not explicitly associated with a sending domain. The domain has to be verified to be set as the default.

Request

DELETE /api/v1/tracking-domains/

Response

// Empty response body

{
  "errors": [
    {
      "param": "domain",
      "message": "domain must be valid",
      "value": "baddomain"
    }
  ]
}

{
  "errors": [
    {
      "message": "resource not found"
    }
  ]
}

Delete a Tracking Domain

DELETE/api/v1/tracking-domains/{domain}

Parameters

domain string required

Delete an existing tracking domain.

Request

GET /api/v1/tracking-domains

Response

{
  "results": [
    {
      "port": 443,
      "domain": "example.domain.com",
      "secure": true,
      "default": true,
      "status": {
        "verified": false,
        "cname_status": "pending",
        "compliance_status": "pending"
      }
    },
    {
      "port": 80,
      "domain": "example2.domain.com",
      "secure": false,
      "default": false,
      "status": {
        "verified": true,
        "cname_status": "valid",
        "compliance_status": "valid"
      },
      "subaccount_id": 215
    }
  ]
}

List All Tracking Domains

GET/api/v1/tracking-domains{?default,subaccounts}

Parameters

default boolean

Restrict results to default domains when true and non-default domains when false.

subaccounts list

Comma delimited list of subaccounts to include in results.

Returns an array with all tracking domains. Each item in the array is a full tracking domain object.