Check DNS API

Table of Contents
Overview
Get DNS Status

GreenArrow CloudMTA

This feature is only available on GreenArrow CloudMTA.

Overview

The Check DNS API looks up the current DNS verification status for a given domain, returning detailed per-record results for any matching Sending Domain or Shared Tracking Domain. It can optionally trigger an immediate DNS recheck rather than returning the data from the last scheduled check.

GreenArrow automatically checks DNS every 15 minutes. Use the recheck_now parameter to request an immediate check when you need up-to-date results.

Get DNS Status

GET /ga/api/v3/eng/check_dns/{domain}

The {domain} is looked up case-insensitively against both Sending Domains and Shared Tracking Domains. A 404 is returned if neither a Sending Domain nor a Shared Tracking Domain matches the given domain.

Parameters

domain string / required	The domain name to look up. Provided as the URL path parameter.
recheck_now integer / optional	Pass `recheck_now=1` to trigger an immediate DNS check before returning results. Omitting this parameter returns the most recently cached results without performing a new check.

Response

sending_domain
hash or null

The Sending Domain matching {domain}, or null if no Sending Domain exists for this domain.

id
integer

The unique identifier of the Sending Domain.

domain
string

The domain name.

dns_verified
boolean

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

dns_regression
boolean

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

wanted_dns_records
array of hashes

The DNS records that must be present for this domain to be verified.

bind string	The full BIND zone file syntax for this record.
type string	The DNS record type: `CNAME` or `TXT`.
name string	The DNS hostname.
value string	The expected record value.
verified boolean	`true` if this record is currently present and correct in DNS. (This is not a one-way flag, like `dns_verified`.)
cname_flattening_detected boolean	`true` if CNAME flattening was detected for this record. Some DNS providers (such as Cloudflare) resolve CNAMEs transparently rather than returning the CNAME itself. GreenArrow detects this and still verifies the record; this flag is informational, indicating the record was verified via a flattened CNAME rather than a direct CNAME.

unwanted_dns_records
array of hashes

DNS records that are present but must be removed for verification to succeed (e.g. conflicting TXT records when using automatic DKIM mode).

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

shared_tracking_domain
hash or null

The Shared Tracking Domain matching {domain}, or null if no Shared Tracking Domain exists for this domain. Has the same structure as sending_domain above.

Example: Sending Domain with All Records Verified

GET /ga/api/v3/eng/check_dns/example.com?recheck_now=1

HTTP/1.1 200 OK

{
  "sending_domain": {
    "id": 1,
    "domain": "example.com",
    "dns_verified": true,
    "dns_regression": false,
    "wanted_dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com",
        "verified": true,
        "cname_flattening_detected": false
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com",
        "verified": true,
        "cname_flattening_detected": false
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com",
        "verified": true,
        "cname_flattening_detected": false
      }
    ],
    "unwanted_dns_records": []
  },
  "shared_tracking_domain": null
}

Example: Sending Domain with Pending Records

GET /ga/api/v3/eng/check_dns/example.com

HTTP/1.1 200 OK

{
  "sending_domain": {
    "id": 1,
    "domain": "example.com",
    "dns_verified": false,
    "dns_regression": false,
    "wanted_dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com",
        "verified": false,
        "cname_flattening_detected": false
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com",
        "verified": true,
        "cname_flattening_detected": false
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com",
        "verified": false,
        "cname_flattening_detected": false
      }
    ],
    "unwanted_dns_records": []
  },
  "shared_tracking_domain": null
}