← Back to Quick Start

Verify DNS Records for Any Domain

Resolve A, MX, TXT, CNAME, and other DNS record types for any hostname with a single API call.

What you'll learn

  • How to query A, MX, TXT, and other DNS record types via the API
  • How to request multiple record types in a single call
  • How to use bulk DNS checks for domain auditing
  • How to verify SPF, DKIM, and DMARC records for email security

Prerequisites

Step 1: Your first call

Look up the A records for example.com:

curl -s -X POST /api/v1/dns/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "hostname": "example.com",
    "recordTypes": ["A"]
  }' | python3 -m json.tool

Expected response:

{
  "hostname": "example.com",
  "records": {
    "A": [
      {"value": "93.184.216.34", "ttl": 3600}
    ]
  },
  "queryTimeMs": 45,
  "nameserver": "8.8.8.8",
  "status": "NOERROR",
  "processingTimeMs": 52
}

Step 2: Understanding the response

records Map of record type to array of results. Each entry has value and ttl (time-to-live in seconds).
status DNS response code: NOERROR (found), NXDOMAIN (domain doesn't exist), SERVFAIL (server error).
queryTimeMs Time spent on the actual DNS query (network latency).
nameserver Which DNS resolver was used to fulfill the request.

Step 3: Common use cases

MX records (email routing)

curl -s -X POST /api/v1/dns/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "hostname": "gmail.com",
    "recordTypes": ["MX"]
  }'
{
  "hostname": "gmail.com",
  "records": {
    "MX": [
      {"value": "alt1.gmail-smtp-in.l.google.com", "priority": 5, "ttl": 3600},
      {"value": "alt2.gmail-smtp-in.l.google.com", "priority": 10, "ttl": 3600},
      {"value": "gmail-smtp-in.l.google.com", "priority": 1, "ttl": 3600}
    ]
  },
  "status": "NOERROR",
  "processingTimeMs": 38
}

TXT records (SPF verification)

curl -s -X POST /api/v1/dns/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "hostname": "google.com",
    "recordTypes": ["TXT"]
  }'
{
  "hostname": "google.com",
  "records": {
    "TXT": [
      {"value": "v=spf1 include:_spf.google.com ~all", "ttl": 3600},
      {"value": "google-site-verification=wD8N7i1JTNTkezJ49swvWW48f8_9xveREV4oB-0Hf5o", "ttl": 3600}
    ]
  },
  "status": "NOERROR",
  "processingTimeMs": 41
}

Multiple record types in one call

curl -s -X POST /api/v1/dns/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "hostname": "example.com",
    "recordTypes": ["A", "AAAA", "MX", "TXT", "NS"]
  }'

All requested record types are resolved in parallel and returned in the records map.

Step 4: Handling errors

Non-existent domain

curl -s -X POST /api/v1/dns/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"hostname": "this-domain-does-not-exist-xyz.com", "recordTypes": ["A"]}'
{
  "hostname": "this-domain-does-not-exist-xyz.com",
  "records": {},
  "status": "NXDOMAIN",
  "processingTimeMs": 120
}

Invalid hostname

{
  "error": "VALIDATION_ERROR",
  "message": "hostname: must be a valid domain name",
  "status": 400
}

Step 5: Integration tips

Python email domain verification

import requests

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

def verify_email_domain(domain):
    """Check if a domain has valid MX records (can receive email)."""
    resp = requests.post(
        f"{API_BASE}/api/v1/dns/check",
        json={"hostname": domain, "recordTypes": ["MX"]},
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    data = resp.json()
    mx_records = data.get("records", {}).get("MX", [])
    return len(mx_records) > 0

# Usage
email = "user@example.com"
domain = email.split("@")[1]
if verify_email_domain(domain):
    print(f"{domain} can receive email")
else:
    print(f"{domain} has no MX records -- email may not be deliverable")

Bulk DNS audit (up to 100 domains)

curl -s -X POST /api/v1/dns/check-bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "targets": [
      {"hostname": "example.com", "recordTypes": ["A", "MX"]},
      {"hostname": "google.com", "recordTypes": ["A", "TXT"]}
    ]
  }'

Next steps