Tracking domains

Open and click tracking serves links and an open image from a tracking domain. Pointing that domain at a branded subdomain of your own keeps tracked links on your brand, and is what turns tracking on for a sending domain.

Why tracking has its own domain

Click tracking rewrites the links in a message to pass through Anypost, and open tracking adds an image that loads from Anypost. Both are URLs, and the domain in those URLs is visible to the recipient and to spam filters.

A branded tracking subdomain, such as track.example.com, keeps those URLs on a domain the recipient recognizes as yours. It is also a precondition: tracking does not run for a sending domain until its tracking subdomain is verified, no matter what the per-message tracking field or the domain defaults say. See Open & click tracking.

Configure tracking on a domain

Tracking is a property of a domain you have already added. PATCH /v1/domains/{id} sets it: turn on opens_enabled or clicks_enabled, and name the subdomain.

curl -X PATCH https://api.anypost.com/v1/domains/domain_550e8400... \
  -H "Authorization: Bearer $ANYPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking": {
      "opens_enabled": true,
      "clicks_enabled": true,
      "subdomain": "track"
    }
  }'

subdomain is the prefix in front of the sending domain. With track on a domain named example.com, the tracking host is track.example.com. It is required whenever either flag is on, and must be unique within your team.

opens_enabled and clicks_enabled set the domain's default tracking behavior. A per-message tracking field overrides that default for one send; see Open & click tracking.

Publish the tracking record

The PATCH response is the domain, with a record to publish under tracking.dns_records: a single CNAME from your tracking host to an Anypost tracking host.

Publish that CNAME at your DNS provider exactly as given. It is one record, separate from the mail-flow records that verify the domain for sending. The mechanics of publishing a CNAME are the same as for those records; see Domains & DNS setup.

Verify the tracking domain

Once the CNAME is published, call the same verify endpoint the sending domain uses:

curl -X POST https://api.anypost.com/v1/domains/domain_550e8400.../verify \
  -H "Authorization: Bearer $ANYPOST_API_KEY"

The response is the domain. Read tracking.status:

`tracking.status`	Meaning
`disabled`	Neither tracking flag is on.
`pending`	Tracking is on, but the CNAME has not yet been observed resolving.
`verified`	The CNAME resolves. Tracking is live for this domain.

While pending, tracking.verification_failure reports the reason: a code of tracking_cname_missing if the record is not found, or tracking_cname_mismatch if it points somewhere unexpected. DNS changes take time to propagate; poll the verify endpoint until tracking.status flips.

Tracking is independent of sending

A tracking-domain problem never affects mail flow. The domain's sending status, its mail-flow records, and your ability to send are all separate. If the tracking CNAME is missing or wrong, messages still send normally; they simply go out without open or click tracking.

This independence is why tracking is safe to add to a domain already in production: a misconfigured tracking CNAME costs you tracking data, never delivery.

Change or turn off tracking

Toggling a flag or changing the subdomain clears the existing tracking verification. The new tracking host has its own CNAME, so you must publish the record from the new tracking.dns_records and verify again.

To turn tracking off, PATCH the domain with both flags false and subdomain set to null. tracking.status returns to disabled, and you can retire the CNAME at your DNS provider.

Where to go next

Open & click tracking: turn tracking on per message once the domain is verified.
Domains & DNS setup: add and verify the sending domain itself.