---
title: "Set tracking domain"
method: PUT
path: "/tracking-domain"
tags: ["Tracking Domain"]
---

# Set tracking domain

`PUT /tracking-domain`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/tracking-domain`
- Auth: HTTP bearer

Sets or changes the company tracking domain. Any subdomain the caller controls works, including one on a root other than the sending domains; a bare registrable domain is rejected because it cannot hold a CNAME. Publish the returned cnameRecord. Sending never waits for it; new emails use the shared Sequenzy tracking domain until it verifies. Saving the current hostname again only rechecks it. Changing the hostname keeps the previous one serving links in emails already sent while its old CNAME stays. Requires the companies:manage scope plus owner or admin access.

## Request body

- object
  - `domain` string, required: Tracking hostname, a subdomain such as links.example.com. A leading https:// and trailing path are ignored.

## Response `200`

Tracking domain saved

- object
  - `success` boolean
  - `message` string: The next step, usually the CNAME to add.
  - `trackingDomain` TrackingDomain: The company tracking domain. Every sending domain uses it for tracked links and opens. It never gates sending; until it verifies, or when it is broken or removed, links use the shared Sequenzy tracking domain.
    - `domain` string, required: Tracking hostname, for example links.example.com.
    - `status` 'not_started' | 'pending' | 'verified' | 'failed', required: Verification status of the CNAME and HTTPS certificate. not_started until the DNS setup is confirmed or checked.
    - `active` boolean, required: True while verified. New emails use this domain only while active.
    - `everVerified` boolean, required: True once this hostname has verified. A failed domain that was verified before is broken rather than unfinished.
    - `sslStatus` string, nullable
    - `verifiedAt` string, date-time, nullable
    - `lastCheckedAt` string, date-time, nullable
    - `error` string, nullable: Latest verification problem, if any.
    - `cnameRecord` object, required: The DNS record to publish.
      - `type` 'CNAME'
      - `name` string
      - `value` string

## Other responses

- `400`: Invalid hostname or a bare root domain
- `401`: Unauthorized
- `403`: Missing the companies:manage scope, or view-only access
- `404`: Company not found
- `409`: The hostname is already connected to another company
- `422`: The request body is missing domain
- `503`: The tracking provider could not register the hostname. Nothing was saved; retry.

## Changes

- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/tracking-domain/put.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/8156dc12d8b4?raw)