const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({hostname: '<string>', name: '<string>'})
};

fetch('https://api.mailchannels.net/tx/v1/custom-tracking-domains', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created_at": "2023-11-07T05:31:56Z",
  "hostname": "<string>",
  "name": "<string>"
}

Register Custom Tracking Domain

Register a custom branded domain for click tracking, open tracking, or unsubscribe handling. By default, MailChannels uses shared domains for these links. Using a custom domain improves brand consistency by replacing shared domains with your own (e.g., click.example.com). Once registered, select the domain at send time using its name.

Before registration completes, two DNS records must be in place:

A TXT record at _mailchannels-verify.<hostname> containing the verification token (returned in the 202 response).
A CNAME record at <hostname> pointing to links.mailchannels.net.

POST

custom-tracking-domains

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({hostname: '<string>', name: '<string>'})
};

fetch('https://api.mailchannels.net/tx/v1/custom-tracking-domains', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created_at": "2023-11-07T05:31:56Z",
  "hostname": "<string>",
  "name": "<string>"
}

Headers

X-Api-Key

string

required

Body

application/json

hostname

string

required

The hostname to register as a custom tracking domain (e.g., click.example.com). The hostname must have a CNAME record pointing to links.mailchannels.net.

name

string

required

A unique label used to select this domain at message send time

Maximum string length: 64

Pattern: ^[a-z0-9-]+$

scope

enum<string>

required

The event type this domain handles

Available options:

click,

open,

unsubscribe

Response

Domain verified and registered

created_at

string<date-time>

required

ISO 8601 timestamp when the domain was registered

hostname

string

required

The registered domain hostname

name

string

required

The label for this custom tracking domain

scope

enum<string>

required

The event type this domain handles

Available options:

click,

open,

unsubscribe

status

enum<string>

required

Current status of the custom tracking domain

Available options:

active,

disabled

Retrieve Custom Tracking Domains Delete Custom Tracking Domain

⌘I