Custom Tracking Domains allow you to customize your email tracking domains to match your brand, giving recipients the security that the links in your messages belong to your domain.

NOTE: This feature is only available in the newer version of the API. Reference our prior version for a list of older methods.

How to Add and Associate a Custom Tracking Domain to a Sender

To add and associate a custom tracking domain to a sender via the API, use these methods, in order:
(1) POST /custom-domain (with appropriate parameters) – create the custom tracking domain record.
(2) GET /senders (with the “email_address” parameter) – retrieve the ID of the sender you wish to associate with the custom tracking domain.
(3) POST /sender/[id]/custom-domain (with the “custom_domain_id” parameter) – associate the sender with the custom tracking domain.

REST Methods

Note: The API is case sensitive; make all parameter entries lower case. All parameters inredare required.

Note: Write actions (POST, UPDATE, DELETE) may take several minutes to propagate and be reflected by the API. If a subsequent read request fails to reflect your changes, please wait a few minutes and try again.

GET /custom-domains

Retrieves a list of up to 25 Custom Tracking Domains.

NOTE: The “valid” response indicates whether or not the domain is available and ready for use.

Parameters

• offset – A starting index of where to begin the list of Custom Tracking Domains.
  Valid values: 0 = Default Returns first 25 Custom Tracking Domains. Accounts with more than 25 Custom Tracking Domains will only receive the first 25 if no start index is entered.
  [any positive integer] = The integer will relate to the first Custom Tracking Domain on the return list. For instance, a start index of 25 will return the next 25 (25 – 49) senders.

Example Results (JSON)

{
    "data": [
        {
            "user_id": 1833,
            "record": "track.mydomain.com",
            "valid":true,
            "created_time": 1412375743,
            "id": 21,
            "last_checked_time": 1412861729.91525
        },
        {
            "user_id": 18,
            "record": "new.mydomain.com",
            "valid":true,
            "created_time": 1412612686,
            "id": 22,
            "last_checked_time": 1412796181.69232
        },
        {
            "user_id": 18,
            "record": "track.another.com",
            "valid":true,
            "created_time": 1412612686,
            "id": 24,
            "last_checked_time": 1412709819.67338
        }
    ],
}

GET /custom-domain/[id]

Retrieves information about a specified Custom Tracking Domain.

NOTE: The “valid” response indicates whether or not the domain is available and ready for use.

Parameters

• None

Example Results (JSON)

{
    "data": [
        {
            "user_id": 18,
            "record": "track.another.com",
            "valid":true,
            "created_time": 1412612686,
            "id": 24,
            "last_checked_time": 1412709819.67338
        }
    ]
}

GET /custom-domain/[id]/validity

Performs a DNS check on a Custom Tracking Domain and updates its status with the result. This check indicates whether the domain can be reached and resolved to trk.email.dynect.com successfully from Dyn’s servers.

NOTE: The “valid” response indicates whether or not the domain is available and ready for use.

Parameters

• None

Example Results

{
   "data":{
      "valid":true,
      "last_checked_time":1415991800
   }
}
}

GET /sender/[id]/custom-domain

Retrieves a Custom Tracking Domain used by a specific Approved Sender.

NOTE: The “valid” response indicates whether or not the domain is available and ready for use.

Parameters

• None

Example Results (JSON)

{
    "data": {
        "record": "track.mydomain.com",
        "valid":true,
        "sender_id": 116,
        "id": 21
    }
}

GET /senders

Retrieves one or more approved senders configured for the account. Returns a list of up to 25 senders at a time.

Required Parameters

• None

Optional Parameters

• offset – A starting index of where to begin the list of Custom Tracking Domains.
• email_address – Specify an email address to limit the results to a specific sender.

Example Results (JSON)

{
   "data":[
      {
         "custom_domain_id":834,
         "custom_domain_record":"track.address.com",
         "user_id":13519,
         "active":true,
         "date_added":1396685357,
         "email_address":"new@address.com",
         "id":10356,
         "seeding_opt_in":0
      }
   ]
}

POST /custom-domain

Creates a Custom Tracking Domain.

NOTE: The “valid” response indicates whether or not the domain is available and ready for use.

Parameters

• record – Required. The specified DNS record of the Custom Tracking Domain.

Examples Results

{
   "message":"track.mydomain.com has been added but is not currently a valid custom tracking domain.",
   "data":{
      "created_time":1415639520,
      "record":"track.mydomain.com",
      "valid":true,
      "id":42,
      "last_checked_time":1415749118
   }
}

POST /sender/[id]/custom-domain

Associate a Custom Tracking Domain with an Approved Sender.

Parameters

• custom_domain_id — Required. The ID of a Custom Tracking Domain used for all mail sent by the specified Approved Sender.

Example Results (JSON)

{
    "message": "Successfully associated sender: 123 with custom domain: 24",
    "data": {
        "custom_domain_id": 24,
        "custom_domain_record": "track.otherdomain.com",
        "user_id": 1833,
        "seeding_opt_in": 0,
        "date_added": 1297374497,
        "email_address": "no-reply@otherdomain.com",
        "id": 123
    }
}

PATCH /sender/[id]/custom-domain

Changes the existing Custom Tracking Domain used by an Approved Sender to a different Custom Tracking Domain.

Parameters

• custom_domain_id — Required. The ID of a Custom Tracking Domain used for all mail sent by the specified Approved Sender.

Example Results (JSON)

{
    "message": "Successfully associated sender: 123 with custom domain: 24",
    "data": {
        "custom_domain_id": 24,
        "custom_domain_record": "track.otherdomain.com",
        "user_id": 1833,
        "seeding_opt_in": 0,
        "date_added": 1297374497,
        "email_address": "no-reply@otherdomain.com",
        "id": 123
    }
}

DELETE /custom-domain/[id]

Deletes the specified Custom Tracking Domain.
Parameters

• None

Example Results (JSON)

{ 
}

DELETE /sender/[id]/custom-domain

Reverts the Custom Tracking Domain used by a specific Approved Sender to the default Dyn Custom Tracking Domain.

Parameters

• None

Example Results (JSON)

{
    "message": "Sender: 123 is now using the default Dyn tracking domain",
}