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, Shared Tracking Domain, or Receiving 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. An immediate check of a domain name is allowed once in 60 seconds (see Rate Limit).

Get DNS Status

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

The {domain} is looked up case-insensitively against Sending Domains, Shared Tracking Domains, and Receiving Domains. A 404 is returned if no match is found across any of these domain types.

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. An immediate check of a domain name is allowed once in 60 seconds. See Rate Limit.

Rate Limit

A request with recheck_now=1 is allowed once in 60 seconds for each domain name. The 60 seconds start at the first request. Upper case and lower case make no difference to the name. A request whose DNS check fails with an error is also counted.

A second request with recheck_now=1 for the same name in that time does not check DNS and does not return the cached results. It fails with the error code rate_limited, and its Retry-After HTTP header gives the number of seconds until an immediate check is allowed again. See Rate Limits for the format of this response.

A request without recheck_now=1 is not limited, and is not counted. Use one to read the results of the last check.

The limit applies only to this API. The DNS check that runs when a domain is created, the check that runs every 15 minutes, and the Recheck DNS button of the user interface are not limited and are not counted.

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

HTTP/1.1 200 OK
Retry-After: 42

{
  "success": false,
  "data": null,
  "error_code": "rate_limited",
  "error_messages": ["rate limit exceeded, please try again in 42 seconds"]
}

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` for Sending Domains and Shared Tracking Domains, or `MX` for Receiving Domains.
name string	The DNS hostname.
value string	The expected record value.
verified boolean or null	`true` if the last DNS check accepted this record, and `false` if it did not. A CNAME can also be accepted when its provider returns matching flattened records. `null` if no DNS check of this domain has completed yet. Unlike `dns_verified`, this is not a one-way flag: each completed DNS check sets it again. It returns to `false` if a later check finds the record missing or wrong, or gets no answer from a nameserver.
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.

receiving_domain
hash or null

The Receiving Domain matching {domain}, or null if no Receiving 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,
  "receiving_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,
  "receiving_domain": null
}