> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a tracking domain

> Adds `hostname` as your organization's tracking domain and answers it with its `dnsTarget`, `pending_dns` when it is new. Then add one CNAME record at your DNS provider: its name is the hostname and its value is `dnsTarget`. The domain is checked every 5 minutes for about a day, or at once with `POST /v1/tracking-domains/{trackingDomainId}/verify`; once the record is found, the hostname is set up and its certificate issued, and it becomes `active`, usually within half an hour. Follow its `status` with `GET /v1/tracking-domains`.

Once it is active, every campaign with click tracking on (`clickTrackingEnabledAt`) sends its tracked links through it: a link in its emails goes to your hostname, where a short redirect page sends the person on to the address you wrote. A campaign with click tracking off sends links as written. The open tracking image, the unsubscribe link, test emails and messages sent outside a campaign never use it.

The hostname must be a subdomain of at least three labels, such as `go.fernway.co`: `fernway.co` answers `422` `invalid_tracking_hostname`. An organization has one tracking domain at a time (`409` `tracking_domain_limit_reached`): delete it to add another. A hostname another organization holds answers `409` `tracking_hostname_already_claimed`. Adding a hostname you deleted after it became active brings that same domain back, with the id it had, checked at once, so it can answer `active` straight away.

Tracking domain calls have a limit of their own, 30 a minute and 1,000 a day. Adding, checking and deleting one also share a tighter one, 10 a minute and 200 a day.

Free. **Scope:** campaigns, with a key that can write.



## OpenAPI

````yaml /openapi.json post /v1/tracking-domains
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/tracking-domains:
    post:
      tags:
        - Campaigns
      summary: Add a tracking domain
      description: >-
        Adds `hostname` as your organization's tracking domain and answers it
        with its `dnsTarget`, `pending_dns` when it is new. Then add one CNAME
        record at your DNS provider: its name is the hostname and its value is
        `dnsTarget`. The domain is checked every 5 minutes for about a day, or
        at once with `POST /v1/tracking-domains/{trackingDomainId}/verify`; once
        the record is found, the hostname is set up and its certificate issued,
        and it becomes `active`, usually within half an hour. Follow its
        `status` with `GET /v1/tracking-domains`.


        Once it is active, every campaign with click tracking on
        (`clickTrackingEnabledAt`) sends its tracked links through it: a link in
        its emails goes to your hostname, where a short redirect page sends the
        person on to the address you wrote. A campaign with click tracking off
        sends links as written. The open tracking image, the unsubscribe link,
        test emails and messages sent outside a campaign never use it.


        The hostname must be a subdomain of at least three labels, such as
        `go.fernway.co`: `fernway.co` answers `422` `invalid_tracking_hostname`.
        An organization has one tracking domain at a time (`409`
        `tracking_domain_limit_reached`): delete it to add another. A hostname
        another organization holds answers `409`
        `tracking_hostname_already_claimed`. Adding a hostname you deleted after
        it became active brings that same domain back, with the id it had,
        checked at once, so it can answer `active` straight away.


        Tracking domain calls have a limit of their own, 30 a minute and 1,000 a
        day. Adding, checking and deleting one also share a tighter one, 10 a
        minute and 200 a day.


        Free. **Scope:** campaigns, with a key that can write.
      operationId: postTrackingDomains
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  description: >-
                    A subdomain of a domain you own, such as `go.fernway.co`,
                    without `https://` or a path: the hostname the tracked links
                    of your campaign emails will go through. It needs at least
                    three labels, so `fernway.co` is refused. It is lower-cased.
                  minLength: 4
                  maxLength: 253
                  example: go.fernway.co
              required:
                - hostname
            example:
              hostname: go.fernway.co
      responses:
        '201':
          description: >-
            The tracking domain: `pending_dns` when it is new. A hostname you
            deleted and add again comes back with the id it had, in the state
            its check finds it in.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - hostname
                  - status
                  - dnsTarget
                properties:
                  id:
                    type: string
                  hostname:
                    type: string
                    description: >-
                      The hostname the tracked links go through, such as
                      `go.fernway.co`.
                  status:
                    type: string
                    enum:
                      - pending_dns
                      - verifying
                      - active
                      - failed
                    description: >-
                      `pending_dns` while it waits for its CNAME record or its
                      certificate, `verifying` while the hostname is set up: it
                      can pass through both more than once. Then `active`, the
                      only state campaigns use it in. `failed` when it has not
                      become active after about a day of checks, or when its
                      setup was lost.
                  dnsTarget:
                    type: string
                    description: >-
                      The value of the one CNAME record to add, the record whose
                      name is `hostname`.
                  verifiedAt:
                    type: string
                    format: date-time
                    description: When it last became active. Absent until it first does.
                  lastCheckedAt:
                    type: string
                    format: date-time
                    description: When it was last checked. Absent before the first check.
                  createdAt:
                    type: string
                    format: date-time
              example:
                id: 6a1f0c2b9d4e8a7f3c5b2e3c
                hostname: go.fernway.co
                status: pending_dns
                dnsTarget: d1x2y3z4abcdef.cloudfront.net
                createdAt: '2026-11-17T09:00:00.000Z'
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.