Sending Domains API

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

GreenArrow CloudMTA

This feature is only available on GreenArrow CloudMTA.

Overview

Sending Domains tie your RFC5322.From domain to a complete, automatically managed DNS configuration for DKIM signing and click/open/bounce tracking. See Sending Domains for a full conceptual overview.

Attributes

The following are the configurable attributes defined for Sending Domains.

sending_domain
hash
/
required

id
integer
/
read-only

A unique automatically generated identifier.

domain
string
/
required

The RFC5322.From domain for this Sending Domain.

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

tracking_subdomain
string
/
optional

The subdomain of domain used for click/open/bounce tracking. Defaults to "trk".

Immutable after creation.
Ignored when shared_tracking_domain is set.
Must be distinct from dkim_selector1 and dkim_selector2.
Must not contain . or _.
May not be specified if a shared_tracking_domain is present.

shared_tracking_domain
hash
/
optional

A Shared Tracking Domain that handles click/open/bounce tracking DNS for this domain instead of the per-domain tracking_subdomain. Either id or domain may be provided when creating or updating.

May not be specified if a tracking_subdomain is present.

id integer	The unique identifier of the Shared Tracking Domain.
domain string	The domain of the Shared Tracking Domain.

track_open
boolean
/
optional

Whether opens are tracked for this domain. Default: true. Overrides the Mail Class setting. If null, then the Mail Class setting is used.

track_click
boolean
/
optional

Whether clicks are tracked for this domain. Default: true. Overrides the Mail Class setting. If null, then the Mail Class setting is used.

route
hash
/
optional

The Route used for email from this domain, unless overridden by an X-GreenArrow-Route header (or an X-GreenArrow-VirtualMTA header.) Overrides the Mail Class setting. Either id or name may be provided when creating or updating. If null, then the Mail Class VirtualMTA setting is used.

id integer	The unique identifier of the route.
name string	The unique name of the route.

dkim_mode
string
/
optional

How DKIM keys are configured for this domain. Immutable after creation. Default: "automatic".

automatic — Two DKIM keys with CNAME delegation to dnsforemail.com (or an ESP-specific dynamic DNS domain). GreenArrow manages the TXT key records; key rotation requires no DNS changes on your end.
txt_single — One DKIM key. You add a TXT record directly containing the public key.
txt_multiple — Two DKIM keys. You add two TXT records directly containing the public keys.

dkim_selector1
string
/
optional

The selector name for the first DKIM key. Immutable after creation. If not supplied, it is filled in with the configured default; the resulting value is always stored, so the selectors are never null.

Must be distinct from dkim_selector2 and tracking_subdomain.

dkim_selector2
string
/
optional

The selector name for the second DKIM key. Immutable after creation. If not supplied, it is filled in with the configured default; the resulting value is always stored, so the selectors are never null.

Required unless dkim_mode is "txt_single".
Must be distinct from dkim_selector1 and tracking_subdomain.

dkim_key_length
integer
/
optional

The bit length for generated DKIM keys. Immutable after creation. Must be 1024 or 2048. Default: 1024.

sending_enabled
boolean
/
optional

Whether email injection is allowed for this domain. Default: true. When false, injection via this domain is prevented regardless of DNS verification status.

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, as of the last DNS check (which is automatically done every 15 minutes). Cleared when the records are fixed. You may use the DNS check API to perform an immediate DNS check.

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 (for example a conflicting record). 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 Sending Domains

GET /ga/api/v3/eng/sending_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`, `mail.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).
sending_enabled boolean / optional	Filter by whether sending is enabled — `true` or `false`.

Response

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

sending_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/sending_domains

HTTP/1.1 200 OK

{
  "sending_domains": [
    {
      "id": 1,
      "domain": "example.com",
      "tracking_subdomain": "trk",
      "track_open": true,
      "track_click": true,
      "dkim_mode": "automatic",
      "dkim_selector1": "ga1",
      "dkim_selector2": "ga2",
      "dkim_key_length": 1024,
      "sending_enabled": true,
      "dns_verified": true,
      "dns_regression": false,
      "shared_tracking_domain": null,
      "route": null
    }
  ],
  "pagination": {
    "page": 0,
    "per_page": 100,
    "num_pages": 1,
    "num_records": 1,
    "next_page_token": null
  }
}

Get a Single Sending Domain

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

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

Example

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

HTTP/1.1 200 OK

{
  "sending_domain": {
    "id": 1,
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "track_open": true,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": true,
    "dns_regression": false,
    "shared_tracking_domain": null,
    "route": null,
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com"
      }
    ],
    "unwanted_dns_records": []
  }
}

Create a Sending Domain

POST /ga/api/v3/eng/sending_domains

Parameters

See the Attributes section for valid parameters.

Example

POST /ga/api/v3/eng/sending_domains

{
  "sending_domain": {
    "domain": "example.com"
  }
}

HTTP/1.1 200 OK

{
  "sending_domain": {
    "id": 1,
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "track_open": true,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": false,
    "dns_regression": false,
    "shared_tracking_domain": null,
    "route": null,
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com"
      }
    ]
  }
}

Update a Sending Domain

PUT /ga/api/v3/eng/sending_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, tracking_subdomain, dkim_mode, dkim_selector1, dkim_selector2, and dkim_key_length are immutable after creation and cannot be changed.

Example

PUT /ga/api/v3/eng/sending_domains/1
PUT /ga/api/v3/eng/sending_domains/example.com

{
  "sending_domain": {
    "route": { "name": "my-route" },
    "track_open": false
  }
}

HTTP/1.1 200 OK

{
  "sending_domain": {
    "id": 1,
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "track_open": false,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": true,
    "dns_regression": false,
    "shared_tracking_domain": null,
    "route": {
      "id": 3,
      "name": "my-route"
    },
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com"
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com"
      }
    ]
  }
}

Delete a Sending Domain

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

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

Example

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

HTTP/1.1 200 OK

{
  "success": true
}