Add Tracking Domain

POSThttps://api.foxreach.io/api/v1/tracking-domains

Requires an API key with the write scope.

Create the domain, then add a CNAME record at your DNS provider pointing the subdomain at cnameTarget. Once DNS resolves, call Verify Tracking Domain until status is active. Sending keeps using the shared tracking domain until then. A workspace can have one tracking domain at a time (a failed one does not count).

Body Parameters#

domainstringbodyrequired

A subdomain such as track.yourcompany.com. A leading https://, a path, a port and a trailing dot are stripped. A root domain such as yourcompany.com is rejected.

Response#

dataobject

The new tracking domain. status starts as pending, or verifying once the certificate is requested.

Show data

idstring

Tracking domain identifier.

domainstring

The tracking subdomain.

statusstring

pending, verifying, active or failed.

cnameTargetstring

The hostname to point your CNAME record at.

sslStatusstring

Certificate status, for example pending_validation or active. null until provisioning has run.

failureReasonstring

Why provisioning or verification failed, or null.

verifiedAtstring

ISO 8601 timestamp, or null.

lastCheckedAtstring

ISO 8601 timestamp, or null.

createdAtstring

ISO 8601 timestamp.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`400`	`Enter a valid subdomain, e.g. track.yourcompany.com`, `Use a subdomain (track.yourcompany.com), not the root domain.` or `That domain is reserved.`
`409`	`A tracking domain already exists. Remove it before adding another.` or `That domain is already registered.`
`422`	`domain` is missing
`501`	`Custom tracking domains are not enabled on this environment.`

Rate Limit#

100 requests per minute, per API key. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch seconds).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Request

curl -X POST "https://api.foxreach.io/api/v1/tracking-domains" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "track.yourcompany.com"}'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
domain = client.tracking_domains.add("track.yourcompany.com")

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const domain = await client.trackingDomains.create({ domain: "track.yourcompany.com" });

Response

{
  "data": {
    "id": "trk_abc123",
    "domain": "track.yourcompany.com",
    "status": "verifying",
    "cnameTarget": "cname.foxtrk.com",
    "sslStatus": "pending_validation",
    "failureReason": null,
    "verifiedAt": null,
    "lastCheckedAt": null,
    "createdAt": "2026-10-31T10:00:00"
  }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026