Shared Tracking Domains API

Table of Contents
Overview
Attributes
Get a List of Shared Tracking Domains
Get a Single Shared Tracking Domain
Create a Shared Tracking Domain
Update a Shared Tracking Domain
Delete a Shared Tracking Domain

GreenArrow CloudMTA

This feature is only available on GreenArrow CloudMTA.

Overview

Shared Tracking Domains allow multiple Sending Domains to share a single set of tracking infrastructure (click/open tracking links and bounce handling) rather than each having their own per-domain tracking subdomain. See Sending Domains for a full conceptual overview.

Attributes

The following are the configurable attributes defined for Shared Tracking Domains.

shared_tracking_domain
hash
/
required

id
integer
/
read-only

A unique automatically generated identifier.

domain
string
/
required

The base domain for this shared tracking setup.

Must be present and unique (case-insensitive).
Immutable after creation.

url_domain
string
/
optional

The hostname used for click/open tracking links. Immutable after creation.

Must be a subdomain of domain, or equal to domain.
Defaults to domain if omitted.

bounce_domain
string
/
optional

The hostname used for bounce/complaint email. Immutable after creation.

Must be a subdomain of domain, or equal to domain.
Defaults to domain if omitted.

dns_verified
boolean
/
read-only

true once all DNS records have been verified. This is a one-way flag — it never returns to false.

dns_regression
boolean
/
read-only

true if the domain was previously verified but DNS records are no longer correct. Cleared when the records are fixed.

dns_records
array of hashes
/
read-only

The DNS records that must be added to your DNS zone for this domain to become verified. Returned only on the single-domain (show) endpoint, not on the list endpoint.

bind string	The full BIND zone file syntax for this record, ready to paste.
type string	The DNS record type: `CNAME` or `TXT`.
name string	The DNS hostname.
value string	The expected record value.

unwanted_dns_records
array of hashes
/
read-only

DNS records that currently exist but must be removed before the domain can verify. Empty when there are none. Returned only on the single-domain (show) endpoint, not on the list endpoint.

type string	The DNS record type.
name string	The DNS hostname.
value string	The record value that was found.

Get a List of Shared Tracking Domains

GET /ga/api/v3/eng/shared_tracking_domains

To keep the list response lightweight, the dns_records and unwanted_dns_records arrays are not included here — fetch a single domain (below) to retrieve them.

Parameters

The following parameters are valid for the above endpoint.

page integer / optional	The page number from which to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` to retrieve the next page based on the prior query results.
domain string / optional	Filter by domain name. This performs a case-insensitive substring match, so `domain=example` would match `example.com`, `tracking.example.org`, etc.
dns_state string / optional	Filter by DNS verification state. One of `not_verified`, `verified_good` (verified and DNS still correct), or `verified_regressed` (verified but DNS has since regressed).

Response

The response will contain a list of Shared Tracking Domains in the following format.

shared_tracking_domains
array of hashes

Each hash contains all of the attributes listed in the Attributes section.

pagination
hash

page integer	The page number of this result set. Page numbers start at 0.
per_page integer	The number of records returned on each page.
num_pages integer	The total number of pages in the result set.
num_records integer	The total number of records that are in the result set.
next_page_token string	A unique identifier that can be used to retrieve the next result set. `null` is returned if this is the last page.

Example

GET /ga/api/v3/eng/shared_tracking_domains

HTTP/1.1 200 OK

{
  "shared_tracking_domains": [
    {
      "id": 1,
      "domain": "tracking.example.com",
      "url_domain": "click.tracking.example.com",
      "bounce_domain": "bounce.tracking.example.com",
      "dns_verified": true,
      "dns_regression": false
    }
  ],
  "pagination": {
    "page": 0,
    "per_page": 100,
    "num_pages": 1,
    "num_records": 1,
    "next_page_token": null
  }
}

Get a Single Shared Tracking Domain

GET /ga/api/v3/eng/shared_tracking_domains/{id}

The {id} may be either the numeric ID or the domain name (case-insensitive).

Example

GET /ga/api/v3/eng/shared_tracking_domains/1
GET /ga/api/v3/eng/shared_tracking_domains/example.com

HTTP/1.1 200 OK

{
  "shared_tracking_domain": {
    "id": 1,
    "domain": "tracking.example.com",
    "url_domain": "click.tracking.example.com",
    "bounce_domain": "bounce.tracking.example.com",
    "dns_verified": true,
    "dns_regression": false,
    "dns_records": [
      {
        "bind": "click.tracking.example.com.  IN  CNAME  click.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "click.tracking.example.com",
        "value": "click.abc123def456.dnsforemail.com"
      },
      {
        "bind": "bounce.tracking.example.com.  IN  CNAME  bounce.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "bounce.tracking.example.com",
        "value": "bounce.abc123def456.dnsforemail.com"
      }
    ],
    "unwanted_dns_records": []
  }
}

Create a Shared Tracking Domain

POST /ga/api/v3/eng/shared_tracking_domains

Parameters

See the Attributes section for valid parameters.

Example

POST /ga/api/v3/eng/shared_tracking_domains

{
  "shared_tracking_domain": {
    "domain": "tracking.example.com",
    "url_domain": "click.tracking.example.com",
    "bounce_domain": "bounce.tracking.example.com"
  }
}

HTTP/1.1 200 OK

{
  "shared_tracking_domain": {
    "id": 1,
    "domain": "tracking.example.com",
    "url_domain": "click.tracking.example.com",
    "bounce_domain": "bounce.tracking.example.com",
    "dns_verified": false,
    "dns_regression": false,
    "dns_records": [
      {
        "bind": "click.tracking.example.com.  IN  CNAME  click.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "click.tracking.example.com",
        "value": "click.abc123def456.dnsforemail.com"
      },
      {
        "bind": "bounce.tracking.example.com.  IN  CNAME  bounce.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "bounce.tracking.example.com",
        "value": "bounce.abc123def456.dnsforemail.com"
      }
    ]
  }
}

Update a Shared Tracking Domain

PUT /ga/api/v3/eng/shared_tracking_domains/{id}

The {id} may be either the numeric ID or the domain name (case-insensitive).

Parameters

See the Attributes section for valid parameters. Note that domain, url_domain, and bounce_domain are immutable after creation and cannot be changed.

Example

There are no mutable fields beyond creation for Shared Tracking Domains. This endpoint is available but has no effect if called with an empty or omitted body.

Delete a Shared Tracking Domain

A Shared Tracking Domain cannot be deleted while any non-deleted Sending Domains reference it. Remove or reassign those Sending Domains first.

DELETE /ga/api/v3/eng/shared_tracking_domains/{id}

The {id} may be either the numeric ID or the domain name (case-insensitive).

Example

DELETE /ga/api/v3/eng/shared_tracking_domains/1
DELETE /ga/api/v3/eng/shared_tracking_domains/example.com

HTTP/1.1 200 OK

{
  "success": true
}