SPF Record Lookup API: Find SPF TXT Records in JSON

Introduction

SPF mistakes often stay invisible until legitimate mail starts landing in spam or an old vendor remains authorized to send on your domain. A missing policy, duplicate SPF records, or a permissive +all rule can turn a small DNS oversight into a deliverability and spoofing problem.

WhoisJSON does not expose a separate SPF-only endpoint. Use the DNS Lookup API /nslookup endpoint, read the TXT array, and select values beginning with v=spf1. The result is structured JSON that your application can inventory, parse, compare, and monitor.

What Is an SPF Record?

Sender Policy Framework, or SPF, is an email authentication policy published as a DNS TXT record. It describes which hosts or delegated services are allowed to send mail using a domain in the SMTP envelope sender.

example.com. 3600 IN TXT
"v=spf1 include:_spf.google.com ip4:192.0.2.0/24 -all"

The record starts with v=spf1, followed by mechanisms and modifiers. Receiving mail systems evaluate those terms during SPF authentication. The DNS response itself gives you the published policy; complete SPF evaluation requires additional recursive DNS resolution and SMTP context.

The protocol behavior is defined in RFC 7208, including record selection, qualifiers, modifiers, and DNS lookup limits.

SPF Lookup API vs SPF Validation API

The distinction matters because a TXT lookup and a complete SPF validator answer different questions.

Query SPF TXT Records in JSON

Authenticate with Authorization: TOKEN=YOUR_API_KEY and query the root domain through /nslookup.

curl "https://whoisjson.com/api/v1/nslookup?domain=example.com" \
  -H "Authorization: TOKEN=YOUR_API_KEY"

The documented response exposes TXT as an array of strings. SPF is one possible use of TXT, so filter the array instead of treating every TXT value as sender policy.

{
  "TXT": [
    "google-site-verification=abc123",
    "v=spf1 include:_spf.google.com ip4:192.0.2.0/24 -all"
  ],
  "MX": [
    {
      "exchange": "mail.example.com",
      "priority": 10
    }
  ],
  "DMARC": [
    "v=DMARC1; p=reject"
  ]
}

How to Interpret Common SPF Mechanisms

A first-level parser can make the raw policy easier to review without claiming to perform complete SPF evaluation.

Qualifiers can also appear before mechanisms: + means pass, - means fail, ~ means soft fail, and ? means neutral. The absence of an explicit qualifier is equivalent to +.

Python Example: Find and Parse SPF

This example finds SPF-like TXT values and extracts first-level terms. It deliberately does not resolve include or redirect targets.

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://whoisjson.com/api/v1"


def parse_spf(record: str) -> dict:
    terms = record.split()
    return {
        "record": record,
        "terms": terms[1:],
        "includes": [
            term.split(":", 1)[1]
            for term in terms
            if term.lstrip("+~-?").startswith("include:")
        ],
        "redirect": next(
            (
                term.split("=", 1)[1]
                for term in terms
                if term.startswith("redirect=")
            ),
            None,
        ),
        "all": next(
            (
                term for term in terms
                if term.lstrip("+~-?") == "all"
            ),
            None,
        ),
    }


def lookup_spf(domain: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/nslookup",
        headers={"Authorization": f"TOKEN={API_KEY}"},
        params={"domain": domain},
        timeout=10,
    )
    response.raise_for_status()
    txt_records = response.json().get("TXT") or []
    spf_records = [
        str(value).strip()
        for value in txt_records
        if str(value).strip().lower().startswith("v=spf1")
    ]

    return {
        "domain": domain,
        "status": (
            "missing" if not spf_records
            else "duplicate" if len(spf_records) > 1
            else "present"
        ),
        "records": [parse_spf(record) for record in spf_records],
    }


print(lookup_spf("example.com"))

Node.js Example: Flag Basic SPF Risks

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://whoisjson.com/api/v1";

async function lookupSpf(domain) {
  const url = new URL(`${BASE_URL}/nslookup`);
  url.searchParams.set("domain", domain);

  const response = await fetch(url, {
    headers: { Authorization: `TOKEN=${API_KEY}` },
  });
  if (!response.ok) {
    throw new Error(`DNS lookup failed: ${response.status}`);
  }

  const data = await response.json();
  const records = (data.TXT ?? [])
    .map(String)
    .map((value) => value.trim())
    .filter((value) =>
      value.toLowerCase().startsWith("v=spf1")
    );

  return {
    domain,
    status:
      records.length === 0
        ? "missing"
        : records.length > 1
          ? "duplicate"
          : "present",
    records,
    findings: [
      ...(records.some((value) =>
        /(^|\s)\+all(\s|$)/i.test(value)
      )
        ? ["policy allows every sender with +all"]
        : []),
      ...(records.some((value) =>
        /(^|\s)~all(\s|$)/i.test(value)
      )
        ? ["policy ends in soft fail (~all)"]
        : []),
    ],
  };
}

lookupSpf("example.com")
  .then(console.log)
  .catch(console.error);

Common SPF Findings

SPF vs MX vs DKIM vs DMARC

For inbound routing, use the MX record lookup guide. For policy enforcement and alignment context, use the DMARC lookup API guide.

Bulk SPF Audits for Domain Portfolios

One /nslookup request per domain returns TXT together with MX, DMARC, MTA-STS, TLS-RPT, and other DNS records. That makes a scheduled SPF inventory useful for provider migrations, vendor reviews, customer-domain onboarding, and domain portfolio governance.

• Store the exact SPF string and timestamp so policy changes are reviewable.
• Flag missing and duplicate records separately; they are different operational failures.
• Compare include and redirect targets with an approved provider inventory.
• Treat +all as urgent and ~all as a review item, not automatic proof of compromise.
• Use bounded concurrency and retry only transient API failures, not valid empty TXT results.

For production retry patterns, see the rate limits and retries guide.

What This SPF Lookup Cannot Prove

FAQ

Conclusion

An SPF record lookup API workflow turns a raw DNS sender policy into data your application can inventory and review. Query /nslookup, filter TXT values for v=spf1, and parse the first-level mechanisms that matter to your provider and security baseline.

Keep lookup and validation separate. WhoisJSON returns the published TXT policy; it does not recursively evaluate every include or decide whether a specific sending IP passes SPF. That boundary makes the result predictable and honest.