# Custom tracking domain One CNAME so tracked links carry your domain instead of ours. Set up in the dashboard. When a broadcast has open or click tracking on, the pixel and the links in it point at a host we run. Without a tracking domain of your own that host is a shared emails.sh address, which means the links in your mail are visibly somebody else's. A custom tracking domain replaces it with a name under your own domain. Three routes, so an assistant that has just verified a sending domain can finish the job without anybody opening a settings page. GET /v1/domains/:id/tracking hands back the record to publish and says whether it resolves yet, POST turns it on once the CNAME is live, and DELETE goes back to the shared host. The dashboard at https://emails.sh/dashboard/domains does the same thing. The host defaults to click. and has to sit under a sending domain of your own that is already verified: a shared sending subdomain is not yours to brand, and the route refuses it with 422 tracking_needs_custom_domain. POST checks DNS live and answers 422 tracking_cname_not_found until the record resolves, rather than rewriting every link in your next send to a hostname that answers nothing. PATCH /v1/domains/:id is the same thing in one field: {"tracking_host": "click.mail.acme.com"} sets it and {"tracking_host": null} clears it, with the same live CNAME check and the same refusals. Use whichever fits the code you are writing. A bare label is expanded under the domain, so "click" on mail.acme.com means click.mail.acme.com. open_tracking and click_tracking are not settings here and a body carrying either is refused by name with 422 tracking_switch_not_supported. ### The record One CNAME. The host has to sit under a custom sending domain you have already verified, which is what keeps somebody from pointing a tracking host at a domain they do not control. click. is the suggested name and the one most people use. | Field | Value | | --- | --- | | Type | CNAME | | Name | click.mail.acme.com, or any host under a domain you have verified | | Value | track.emails.sh | | TTL | Whatever your host defaults to | Confirm the CNAME: ```bash # Check it resolves before you rely on it dig CNAME click.mail.acme.com +short # expect: track.emails.sh. ``` ### What the links become Two URL shapes get rewritten, and both take the tracking host as their base. The open pixel is /o/.gif and a tracked link is /c/. Before and after: ```text Without a tracking domain: https://emails.sh/o/f3a91c07-4e28-4b6d-9c15-8d02a7e5b431.gif https://emails.sh/c/7d2e9a10 With click.mail.acme.com pointed at track.emails.sh: https://click.mail.acme.com/o/f3a91c07-4e28-4b6d-9c15-8d02a7e5b431.gif https://click.mail.acme.com/c/7d2e9a10 ``` ### Why bother - **The links look like yours**: A recipient hovering a link in your newsletter sees your domain. On a shared host they see ours, which is the sort of thing that makes a careful person not click. - **Reputation is yours**: A shared tracking host carries everybody's links, and a link scanner that has seen something bad on it has seen it on the same hostname as yours. - **It survives a move**: The CNAME is yours. Pointing it somewhere else later is a DNS change rather than a rewrite of every link already sitting in an inbox. ### Tracking is off by default Nothing is tracked unless you ask for it. On a broadcast that is track_opens and track_clicks, both defaulting to off. A transactional send through POST /v1/emails is not tracked and has no pixel in it. Leave it off for transactional mail. A receipt does not need a pixel, and an invisible image in a password reset is the kind of thing that gets a message filed as suspicious by a scanner that has no way to tell your pixel from anybody else's. One link is never rewritten under any setting: the one-click unsubscribe. Putting a redirect in front of it breaks RFC 8058, which is the rule Gmail and Yahoo cite in their bulk sender requirements. See /docs/topics. Open numbers are a floor whatever host serves the pixel. Read /docs/analytics before you make a decision out of them. --- Base URL: https://emails.sh/v1. Auth: `Authorization: Bearer esh_...`. Whole API in one file: https://emails.sh/llms.txt. All documentation: https://emails.sh/docs.md.