Skip to main content

​
What is custom tracking?

By default, MailChannels uses shared domains for click-tracking links, open-tracking pixels, and unsubscribe URLs embedded in your emails. A custom tracking domain replaces those shared domains with one you own (e.g., click.example.com), improving brand consistency and deliverability. Each custom tracking domain is defined by three user-configurable fields:
  • hostname — the subdomain you control, e.g., click.example.com.
  • scope — the event type it handles: click, open, or unsubscribe.
  • name — a unique short label used to select this domain at send time (e.g., clickdemo).
Custom tracking domains are not available on the free developer plan. Upgrade to a paid plan to enable it.

​
Registering a custom tracking domain

1

Submit the registration request

Provide the hostname, scope, and a unique name for the domain.
#!/usr/bin/env bash
# Register a custom click-tracking domain.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"

curl -X POST "https://api.mailchannels.net/tx/v1/custom-tracking-domains" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "name": "clickdemo",
  "hostname": "click.example.com",
  "scope": "click"
}
JSON
If the domain has not been verified yet, the API returns the DNS records you need to add. The domain is not active at this stage.
{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "txt_record_name": "_mailchannels-verify.click.example.com",
  "txt_record_value": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "Add a DNS TXT record: _mailchannels-verify.click.example.com → \"550e8400-e29b-41d4-a716-446655440000\" and a CNAME record: click.example.com → links.mailchannels.net, then retry this request."
}
2

Add the required DNS records

Add both records to your domain’s DNS before retrying:
_mailchannels-verify.click.example.com  TXT    550e8400-e29b-41d4-a716-446655440000
click.example.com                        CNAME  links.mailchannels.net
The TXT record proves you own the hostname. The CNAME record routes tracking traffic to MailChannels infrastructure.
3

Re-register to confirm

Once both records have propagated, call the registration endpoint again with the same request body. If verification succeeds, the API returns the domain in the active status.
If either record is not yet visible to MailChannels, the response includes an instructions field describing which record is still missing. Wait for DNS propagation and retry.

​
Sending with custom tracking

Reference the custom tracking domain by its name in tracking_settings or unsubscribe_settings when sending a message. The domain must have active status. A full send example: 
#!/usr/bin/env bash
# Send an email with the custom click-tracking, open-tracking, and unsubscribe-handling domains.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST "https://api.mailchannels.net/tx/v1/send" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hello! Visit our <a href=\"https://example.net/sale\">sale page</a>.</p>"
    }
  ],
  "tracking_settings": {
    "click_tracking": {
      "enable": true,
      "custom_domain_name": "clickdemo"
    },
    "open_tracking": {
      "enable": true,
      "custom_domain_name": "opendemo"
    },
  },
  "unsubscribe_settings": {
    "custom_domain_name": "unsubscribedemo"
  }
}
JSON

​
Managing custom tracking domains

​
Listing domains

Retrieve all registered domains for your account. Optional filters include name, status, and scope. 
#!/usr/bin/env bash
# Retrieve custom tracking domains for the account.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY (parent or sub-account) before running}"

curl -X GET "https://api.mailchannels.net/tx/v1/custom-tracking-domains" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY"

​
Updating a domain

Rename a domain or toggle its status between active and disabled.
Reactivating a disabled domain triggers DNS re-verification. Both the TXT ownership record and the CNAME record must be in place. If either is missing, the response includes an instructions field describing what to add.
#!/usr/bin/env bash
# Update a custom tracking domain.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${TRACKING_DOMAIN_HOSTNAME:?Set TRACKING_DOMAIN_HOSTNAME to the hostname of the custom tracking domain to be updated}"
: "${SCOPE:?Set SCOPE to the scope of the custom tracking domain to be updated}"

curl -X PATCH "https://api.mailchannels.net/tx/v1/custom-tracking-domains/$TRACKING_DOMAIN_HOSTNAME/$SCOPE" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "status": "disabled",
  "name": "dontuse"
}
JSON

​
Deleting a domain

Delete a domain by its hostname and scope. The same hostname and scope can be re-registered if needed.
Any tracking links or unsubscribe URLs in previously sent emails that used a deleted domain will stop working immediately.
#!/usr/bin/env bash
# Delete a custom tracking domain permanently.
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${TRACKING_DOMAIN_HOSTNAME:?Set TRACKING_DOMAIN_HOSTNAME to the hostname of the custom tracking domain to be removed}"
: "${SCOPE:?Set SCOPE to the scope of the custom tracking domain to be removed}"

curl -X DELETE "https://api.mailchannels.net/tx/v1/custom-tracking-domains/$TRACKING_DOMAIN_HOSTNAME/$SCOPE" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \