BIMI Record Lookup API: Check Brand Indicators in JSON

Introduction

BIMI, or Brand Indicators for Message Identification, is the DNS record that lets a domain publish a brand logo location for supporting email clients. It sits after the core authentication stack: MX routes mail, SPF authorizes senders, DMARC defines enforcement, and BIMI adds a visible brand signal when the receiving mailbox provider supports it.

WhoisJSON returns BIMI records through the documented DNS Lookup API /nslookup endpoint. Query the root domain, then read the BIMI array alongside DMARC, MX, TXT, MTASTS and TLSRPT.

What Is a BIMI Lookup API?

A BIMI lookup API accepts a domain name, checks DNS for the domain's published BIMI record, and returns the result as structured JSON. Your application can then decide whether the domain has a BIMI record, whether a logo URL is present, and whether the broader email security context looks mature enough for a brand indicator workflow.

BIMI is not a replacement for DMARC. In practice, BIMI should be reviewed with DMARC policy, MX presence, SPF TXT records, and transport records such as MTA-STS and TLS-RPT.

BIMI Lookup vs DMARC Lookup

BIMI and DMARC are related, but they answer different questions. Keeping that boundary clear makes audits more useful.

For policy enforcement, use the DMARC lookup API guide. For sender authorization, use the SPF record lookup API guide. This article focuses on BIMI as the brand-indicator layer.

Query BIMI Records in JSON

Authenticate with the Authorization: TOKEN=YOUR_API_KEY header and pass the root domain as the domain query parameter.

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

The response can include BIMI plus supporting email records in one JSON payload.

{
  "MX": [
    { "exchange": "mail.example.com", "priority": 10 }
  ],
  "TXT": [
    "v=spf1 include:_spf.example.net -all"
  ],
  "DMARC": [
    "v=DMARC1; p=reject; rua=mailto:[email protected]"
  ],
  "BIMI": [
    "v=BIMI1; l=https://example.com/bimi.svg; a=self"
  ],
  "MTASTS": [
    "v=STSv1; id=20260628000000Z"
  ],
  "TLSRPT": [
    "v=TLSRPTv1; rua=mailto:[email protected]"
  ]
}

How to Interpret BIMI Results

Start by checking whether the domain is an active email domain. Then inspect the BIMI record as a brand-security signal, not as a standalone authentication verdict.

Python Example: Audit BIMI Records

This example extracts BIMI, DMARC, MX, and SPF context from the documented DNS response.

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://whoisjson.com/api/v1"
HEADERS = {"Authorization": f"TOKEN={API_KEY}"}


def find_spf(txt_records: list[str]) -> list[str]:
    return [
        value for value in txt_records
        if value.lower().startswith("v=spf1")
    ]


def audit_bimi(domain: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/nslookup",
        headers=HEADERS,
        params={"domain": domain},
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    mx_records = data.get("MX") or []
    txt_records = data.get("TXT") or []
    dmarc_records = data.get("DMARC") or []
    bimi_records = data.get("BIMI") or []

    findings = []
    if mx_records and not dmarc_records:
        findings.append("MX exists but no DMARC record was found")
    if mx_records and not bimi_records:
        findings.append("MX exists but no BIMI record was found")

    return {
        "domain": domain,
        "hasMx": bool(mx_records),
        "hasSpf": bool(find_spf(txt_records)),
        "hasDmarc": bool(dmarc_records),
        "hasBimi": bool(bimi_records),
        "bimi": bimi_records,
        "findings": findings,
    }


print(audit_bimi("example.com"))

Node.js Example: Batch Check Domains

For vendor reviews or customer-domain onboarding, keep each domain's result separate so one bad lookup does not hide the rest of the audit.

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

async function lookupDns(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 for ${domain}: ${response.status}`);
  }
  return response.json();
}

async function auditDomain(domain) {
  const dns = await lookupDns(domain);
  const txt = dns.TXT ?? [];
  const spf = txt.filter((value) =>
    value.toLowerCase().startsWith("v=spf1")
  );

  return {
    domain,
    hasMx: (dns.MX ?? []).length > 0,
    hasSpf: spf.length > 0,
    hasDmarc: (dns.DMARC ?? []).length > 0,
    hasBimi: (dns.BIMI ?? []).length > 0,
    bimi: dns.BIMI ?? [],
  };
}

async function main() {
  const domains = ["example.com", "whoisjson.com"];
  const results = await Promise.all(
    domains.map((domain) => auditDomain(domain))
  );
  console.table(results);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Practical Use Cases

• Check customer domains before enabling branded email features.
• Audit vendors that send business-critical mail on behalf of your company.
• Track unexpected BIMI logo URL changes as part of brand monitoring.
• Combine BIMI with DMARC, SPF, MX, MTA-STS, and TLS-RPT in email security scorecards.
• Build a domain portfolio report that separates routing, authentication, transport security, and brand indicators.

Where BIMI Fits in the Email Security Cluster

BIMI is the brand indicator layer of a broader DNS email audit. A useful workflow checks the records in order: MX for mail routing, SPF for authorized senders, DMARC for policy enforcement, BIMI for brand indication, then MTA-STS and TLS-RPT for transport security reporting.

What This Lookup Cannot Prove

FAQ

Conclusion

BIMI lookup is a practical addition to email security audits because it connects brand visibility with DNS-based authentication context. Query /nslookup once, read BIMI, DMARC, MX, TXT, MTASTS, and TLSRPT, then store the DNS snapshot for onboarding, vendor reviews, brand protection, or continuous monitoring.

Keep the boundary clear: WhoisJSON returns the DNS records. Full BIMI program validation, logo asset checks, and mailbox-provider display behavior remain separate checks that you can layer on top.