Tracking Domains

Tracking domains are used in engagement tracking to report opens and clicks in your messages. When open and click tracking is enabled, you can set up a tracking domain which wraps the tracking pixel and all links in your messages.

As an example, for SparkPost.com, the tracking domain is spgo.io. Your message contains a link to http://www.some-website.com/some-article. That link gets wrapped and the resulting HTML would look something like this:

<a href="http://spgo.io/e/nInKCLCf9wnO2brop7RTsg...">Check out this excellent article</a>

With a tracking domain you can replace the domain part of the link. So if your tracking domain was example.domain.com, your HTML would look like this:

<a href="http://example.domain.com/e/nInKCLCf9wnO2brop7RTsg...">Check out this excellent article</a>
Note: Use of a tracking domain requires modification of your DNS records to include a CNAME record.
Note: For SparkPost, in order to use HTTPS on tracking domains follow this guide.

Using Postman

If you use Postman you can click the following button to import the SparkPost API as a collection:

Run in Postman

Tracking Domains Attributes

Field Type Description Required Notes
domain string Name of the tracking domain yes Example: example.domain.com
port integer Determines the port to be used when constructing the tracking URL no Example: 8080
secure boolean Should the tracking URL should use https? no If false (the default), http will be used.
Enterprise customers may set "secure": true to use https
default boolean Should the default tracking domain be used when not explicitly set no There can only be one default domain. Defaults to false.
status JSON object JSON object containing status details, including whether this domain’s ownership has been verified no Read only. For a full description, see the Status Attributes.

Port/Secure Attributes

Upon creation of a tracking domain, the values for port and secure are set according to the following table:

port (input) secure (input) port (value) secure (value)
provided value provided value provided value provided value
not provided not provided 80 false
not provided false 80 false
not provided true 443 true
443 not provided 443 true
provided value (not 443) not provided provided valued false

Status Attributes

Detailed status for this tracking domain is described in a JSON object with the following fields:

Field Type Description Default Notes
verified boolean Whether domain has been verified false Read only. This field will return true if cname_status is valid.
cname_status string Verification status of CNAME configuration unverified Read only. Valid values are unverified, pending, invalid or valid.
compliance_status string Compliance status Read only. Valid values are pending, valid, or blocked.

Create and List

Create a Tracking Domain

POST/api/v1/tracking-domains

Create a tracking domain. A tracking domain cannot be set as the default until it is verified.

Note: For SparkPost customers, only the domain is required in the POST request body. The values for port (80) and secure (false) are not configurable.

Examples

Request

POST /api/v1/tracking-domains

{
  "domain": "example.domain.com",
  "port": 80,
  "secure": false,
  "default": false
}

Response (HTTP status code: 200)

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

Response (HTTP status code: 400)

{
  "errors": [
    {
      "code": "7000",
      "message": "restricted domain",
      "description": "Please contact us at support@sparkpost.com to get this domain authorized for your account."
    }
  ]
}

Response (HTTP status code: 409)

{
  "errors": [
    {
      "code": "1602",
      "message": "resource conflict",
      "description": "The tracking domain already exists."
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Tracking domain 'example.domain.com' unverified."
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error validating domain name syntax for domain: 'example..domain.com'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name length too short for domain: 'ex'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name contains no '.'(s) for domain: 'exampledomaincom'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Error domain name contains invalid characters or spaces for domain: 'example*&#.domain.com'"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1400",
      "message": "required field is missing",
      "description": "field 'domain' is required"
    }
  ]
}

List all Tracking Domains

GET/api/v1/tracking-domains

Retrieve a list of all tracking domains.

Note: For SparkPost customers, port (80) and secure (false) are not returned since they are not configurable.

Examples

Request

GET /api/v1/tracking-domains

Response (HTTP status code: 200)

{
  "results": [
    {
      "port": 8080,
      "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"
      }
    }
  ]
}

Retrieve, Update, and Delete

Retrieve a Tracking Domain

GET/api/v1/tracking-domains/{domain}
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Retrieve an existing tracking domain.

Note: For SparkPost customers, port (80) and secure (false) are not returned since they are not configurable.

Examples

Request

GET /api/v1/tracking-domains/example.domain.com

Response (HTTP status code: 200)

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

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Resource not found: example.domain.com"
    }
  ]
}

Update a Tracking Domain

PUT/api/v1/tracking-domains/{domain}
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Update the attributes of an existing tracking domain. A tracking domain cannot be set as the default until it is verified. If a tracking domain is set to the default, and there is already a default domain, the default is changed.

Note: For SparkPost customers, port (80) and secure (false) cannot be updated since they are not configurable.

Examples

Request

PUT /api/v1/tracking-domains/example.domain.com

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

Response (HTTP status code: 200)

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

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Resource not found: example.domain.com"
    }
  ]
}

Response (HTTP status code: 422)

{
  "errors": [
    {
      "code": "1300",
      "message": "invalid data format/type",
      "description": "Tracking domain 'example.domain.com' unverified."
    }
  ]
}

Delete a Tracking Domain

DELETE/api/v1/tracking-domains/{domain}
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Delete an existing tracking domain.

Examples

Request

DELETE /api/v1/tracking-domains/example.domain.com

Response (HTTP status code: 204)

Empty response body

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Resource not found: example.domain.com"
    }
  ]
}

Verify

Verify a Tracking Domain

POST/api/v1/tracking-domains/{domain}/verify
URI Parameters
domain(required)  

domain name

Example: example.domain.com

Initiate a check against the CNAME DNS record for the specified tracking domain. The domain’s status object is returned on success.

Examples

Request

POST /api/v1/tracking-domains/example.domain.com/verify

Response (HTTP status code: 200)

Response Headers
  • Content-Type: application/json; charset=utf-8
{
  "results": {
    "verified": true,
    "cname_status": "valid",
    "compliance_status": "valid"
  }
}

Response (HTTP status code: 404)

{
  "errors": [
    {
      "code": "1600",
      "message": "resource not found",
      "description": "Resource not found: example.domain.com"
    }
  ]
}