Custom domains

Every campaign’s open and click tracking runs on a domain of yours, track.<your domain> by default, over HTTPS. You can also serve the API and unsubscribe links from your own domain, such as api.example.com. We request the certificates and run the CloudFront side; you add two DNS records for each domain.

Set your domains

The tracking domain is required. The API domain is optional.

curl -X POST "$BASE/setup/domains" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"trackingDomain":"track.example.com","apiDomain":"api.example.com"}'

The response lists, for each domain, a certificate validation CNAME and its status, pending_validation.

Add the records

For each domain, add:

• the certificate validation CNAME from the response, and
• a CNAME from the domain itself to the target shown on the console’s Setup page.

The full list is in DNS records.

Watch them go live

curl "$BASE/setup/domains" -H "Authorization: Bearer $KEY"

Each domain moves from pending_validation to issued when the certificate is validated, then deploying, then live. Validation usually takes minutes once the record resolves; deploying takes a few more.

Check it worked: both domains show live, and the tracking_domain and api_domain checks in /health show "ok": true.

What changes when they’re live

• Links in new emails use your tracking domain, over HTTPS.
• With an API domain, unsubscribe links become https://api.example.com/u/<token>, and you can call the API at https://api.example.com/v1. Our own base URL keeps working too.
• Unsubscribe links in emails sent before you added the API domain use our domain, and keep working.

To change a domain, send POST /setup/domains with the new name. We request a new certificate and remove the old domain’s CloudFront setup straight away, so tracking links in emails already sent on the old tracking domain stop being counted. Change the tracking domain between campaigns, not during one.