MX lookup API

How it works

Reads the MX records from the domain's own nameservers (reached by walking down from a root server), beside Google's and Cloudflare's cached copies, and follows every mail server to its IPv4 and IPv6 addresses, networks and reverse names. It names the mailbox provider and any gateway in front of it (Mimecast, Proofpoint…) from the providers' documented MX values, with SPF and Autodiscover as evidence when a gateway hides the mailboxes.

It reads the mail security records too: SPF with its DNS lookup count, DMARC (with RFC 9989's tree walk to a parent's record), MTA-STS with its policy file matched against the live MX, TLS-RPT, DANE (TLSA under DNSSEC) and BIMI. Null MX (RFC 7505), no MX (the implicit MX of RFC 5321 §5.1), MX hosts that are aliases or IP addresses, and Microsoft's mx.microsoft migration come back as issues, worded as the MX Lookup page words them.

The name is looked up as given: www.example.com has MX records of its own, so it is never swapped for its parent; parentZone offers the parent's when the name has none. No mail server is connected to (the page's SMTP test isn't part of the API).

Answers kept: Kept for the MX records' TTL, 30 seconds to 5 minutes (30 seconds when a part failed), shared with the MX Lookup page. A kept answer carries an `Age` header, and the resolvers' TTLs are counted down.

Query parameters

• domainstringrequired
  A domain, a host name or an e-mail address (its domain); URLs and IDNs in Unicode work too.

Response fields

200 with this JSON object, plus tookMs, and incomplete with warnings when a source failed. Fields marked optional appear only when they apply.

• queryobjectalways
  What was looked up, normalised (lower case, no trailing dot, IDNs as Punycode).
  • domainstringalways
    The name looked up, lower case, IDNs as Punycode.
• verdictstringalways
  mail (MX hosts receive mail), null_mx (accepts no mail, on purpose), null_mx_conflict (a null MX beside other hosts), no_mx (no MX, but the name's own address receives: the implicit MX), no_mail (no MX and no address), nxdomain, servfail or no_answer.

  one of "mail", "null_mx", "null_mx_conflict", "no_mx", "no_mail", "nxdomain", "servfail", "no_answer"

• zonestring or nullalways
  The zone the name lives in, as the walk from the root found it.
• answerobject or nullalways
  The MX answer that counts: the zone's own, unless it couldn't be had; then Google's, then Cloudflare's.
  Show 9 fields

  • sourcestringalways
    Who answered: authoritative (the zone's own nameserver, the fresh truth), google (Google Public DNS's cached copy) or cloudflare (Cloudflare 1.1.1.1's).

    one of "authoritative", "google", "cloudflare"

  • serverstring or nullalways
    The server that answered.
  • ipstring or nullalways
    Its address.
  • viaCloudflarebooleanalways
    The zone is on Cloudflare's nameservers, which our servers can't connect to: this is 1.1.1.1's answer, from the same network.
  • statusstringalways
    The answer: ok (records came back), nodata (the name exists without them), nxdomain (no such name), servfail, refused, timeout, error or unreadable (an answer our decoder refuses).

    one of "ok", "nodata", "nxdomain", "servfail", "refused", "timeout", "error", "unreadable"

  • authoritativeboolean or nullalways
    The AA flag.
  • dnssecValidatedboolean or nullalways
    A resolver's AD flag; null for the zone's own answer.
  • negativeTtlinteger or nullalways
    For no MX or no such name: how long the miss is cached, in seconds (RFC 2308).
  • cnameChainarray of objectsalways
    The CNAMEs the answer followed, in order.
    Show 3 fields

    • namestringalways
      The alias.
    • targetstringalways
      The name it points to.
    • ttlintegeralways
      The record's TTL, in seconds.
• mxarray of objectsalways
  The MX records in delivery order, each host followed to its addresses (at most 12 hosts).
  Show 8 fields

  • priorityintegeralways
    Lower is tried first; equal numbers share the load.
  • hoststringalways
    The host name; . for a null MX.
  • ttlintegeralways
    The MX record's TTL, in seconds.
  • providerobject or nullalways
    The provider the host belongs to, matched from 110+ providers' documented MX values; null when none matches.
    Show 4 fields

    • idstringalways
      A stable id, e.g. google-workspace, microsoft-365, proofpoint.
    • namestringalways
      The provider's name.
    • kindstringalways
      mailbox (hosts mailboxes), gateway (filters mail in front of them), forwarder, inbound (a receiving service) or consumer (personal mail).

      one of "mailbox", "gateway", "forwarder", "inbound", "consumer"

    • regionstringoptional
      A data-centre region read from the host (Zoho's TLD, Amazon's region…), when it names one.
  • statusstring or nullalways
    Its addresses: ok, nxdomain (the host doesn't exist), nodata (no A or AAAA), literal (an IP address written as the host: invalid), timeout, error; null_mx for .; null past the first 12 hosts.

    one of "ok", "nxdomain", "nodata", "literal", "timeout", "error", "null_mx", null

  • cnamestring or nullalways
    The host is an alias (CNAME) for this name, which RFC 2181 §10.3 forbids for MX hosts.
  • addressesarray of objectsalways
    Its IPv4 then IPv6 addresses.
    Show 3 fields

    • ipstringalways
      The IPv4 or IPv6 address.
    • networkobject or nullalways
      The network behind the address (Team Cymru); null when unknown.
      Show 4 fields

      • asnintegeralways
        The AS number that announces the address.
      • namestringalways
        The network's name, cleaned ("Google", "Amazon.com").
      • prefixstringalways
        The announced prefix the address is in, e.g. 8.8.8.0/24.
      • countrystringalways
        The network's registration country (ISO 3166-1 alpha-2), as Team Cymru has it.
    • reverseobject or nullalways
      Its PTR name and whether that name resolves back to it (forward-confirmed reverse DNS); null when not checked (the first address of each family per host is).
      Show 2 fields

      • namestring or nullalways
        The PTR name; null when it has none.
      • forwardConfirmedbooleanalways
        The PTR name resolves back to this address.
  • dnssecSignedboolean or nullalways
    Its address answer was DNSSEC-validated: where DANE can work.
• implicitMxobject or nullalways
  With no MX: the name's own addresses, where senders deliver instead (RFC 5321 §5.1).
  • addressesarray of objectsalways
    Its IPv4 then IPv6 addresses.
    Show 3 fields

    • ipstringalways
      The IPv4 or IPv6 address.
    • networkobject or nullalways
      The network behind the address (Team Cymru); null when unknown.
      Show 4 fields

      • asnintegeralways
        The AS number that announces the address.
      • namestringalways
        The network's name, cleaned ("Google", "Amazon.com").
      • prefixstringalways
        The announced prefix the address is in, e.g. 8.8.8.0/24.
      • countrystringalways
        The network's registration country (ISO 3166-1 alpha-2), as Team Cymru has it.
    • reverseobject or nullalways
      Its PTR name and whether that name resolves back to it (forward-confirmed reverse DNS); null when not checked (the first address of each family per host is).
      Show 2 fields

      • namestring or nullalways
        The PTR name; null when it has none.
      • forwardConfirmedbooleanalways
        The PTR name resolves back to this address.
  • ttlinteger or nullalways
    The A (else AAAA) record's TTL, in seconds.
• parentZoneobject or nullalways
  With no MX at the name: its zone apex's MX records, offered (never swapped in).
  • namestringalways
    The parent zone.
  • mxarray of objectsalways
    Its MX records.
    Show 3 fields

    • priorityintegeralways
      Lower is tried first; equal numbers share the load.
    • hoststringalways
      The mail server; . is a null MX.
    • ttlintegeralways
      The record's TTL, in seconds.
  • providerobject or nullalways
    The provider the host belongs to, matched from 110+ providers' documented MX values; null when none matches.
    Show 4 fields

    • idstringalways
      A stable id, e.g. google-workspace, microsoft-365, proofpoint.
    • namestringalways
      The provider's name.
    • kindstringalways
      mailbox (hosts mailboxes), gateway (filters mail in front of them), forwarder, inbound (a receiving service) or consumer (personal mail).

      one of "mailbox", "gateway", "forwarder", "inbound", "consumer"

    • regionstringoptional
      A data-centre region read from the host (Zoho's TLD, Amazon's region…), when it names one.
• providerobject or nullalways
  Who runs the mail; null when the name has no MX hosts.
  Show 4 fields

  • mailboxobject or nullalways
    Who holds the mailboxes; null when not visible from DNS (a gateway that SPF and Autodiscover don't explain).
    Show 5 fields

    • idstringalways
      A stable id, e.g. google-workspace, microsoft-365, proofpoint.
    • namestringalways
      The provider's name.
    • kindstringalways
      mailbox (hosts mailboxes), gateway (filters mail in front of them), forwarder, inbound (a receiving service) or consumer (personal mail).

      one of "mailbox", "gateway", "forwarder", "inbound", "consumer"

    • regionstringoptional
      A data-centre region read from the host (Zoho's TLD, Amazon's region…), when it names one.
    • evidencearray of objectsalways
      Why it is named.
      Show 2 fields

      • kindstringalways
        mx, spf (an include), autodiscover or asn.

        one of "mx", "spf", "autodiscover", "asn"

      • valuestringalways
        The value that matched.
  • gatewayobject or nullalways
    The filtering gateway the MX points to, in front of the mailboxes; null for none.
    Show 5 fields

    • idstringalways
      A stable id, e.g. google-workspace, microsoft-365, proofpoint.
    • namestringalways
      The provider's name.
    • kindstringalways
      mailbox (hosts mailboxes), gateway (filters mail in front of them), forwarder, inbound (a receiving service) or consumer (personal mail).

      one of "mailbox", "gateway", "forwarder", "inbound", "consumer"

    • regionstringoptional
      A data-centre region read from the host (Zoho's TLD, Amazon's region…), when it names one.
    • evidencearray of objectsalways
      Why it is named.
      Show 2 fields

      • kindstringalways
        mx, spf (an include), autodiscover or asn.

        one of "mx", "spf", "autodiscover", "asn"

      • valuestringalways
        The value that matched.
  • ownServersbooleanalways
    The MX hosts sit in the domain's own zone and match no provider: its own servers.
  • multipleProvidersarray of stringsalways
    Provider families when the MX hosts sit at more than one mailbox provider (a move in progress); empty otherwise.
• securityobject or nullalways
  The mail security records; null when the name doesn't exist or nothing answered.
  Show 9 fields

  • spfobject or nullalways
    The SPF record (RFC 7208); null when there is none.
    Show 5 fields

    • recordstringalways
      The record.
    • lookupsintegeralways
      DNS-querying terms, nested includes counted; more than 10 is a permanent error.
    • allstring or nullalways
      The final all term (-all, ~all, ?all, +all); null with redirect= or none.
    • multipleRecordsbooleanalways
      More than one SPF record: a permanent error.
    • missingIncludesarray of stringsalways
      Included names that publish no SPF record.
  • dmarcobject or nullalways
    The DMARC record (RFC 9989); null when there is none, at the name or its parents.
    Show 8 fields

    • recordstringalways
      The record.
    • policystring or nullalways
      p=.
    • subdomainPolicystring or nullalways
      sp=, when set.
    • effectivePolicystring or nullalways
      The policy that applies to this name: p=, or sp= for a record found at a parent.
    • pctinteger or nullalways
      pct= (removed in RFC 9989; older records carry it).
    • ruaarray of stringsalways
      Aggregate report addresses.
    • inheritedFromstring or nullalways
      The parent the record was found at, when the name has none of its own.
    • multipleRecordsbooleanalways
      More than one DMARC record: receivers discard them all.
  • mtaStsobject or nullalways
    MTA-STS (RFC 8461); null when no _mta-sts record exists.
    Show 4 fields

    • recordstringalways
      The _mta-sts TXT record.
    • idstring or nullalways
      Its id=.
    • delegatedTostring or nullalways
      _mta-sts is a CNAME to this name (a delegated policy).
    • policyobject or nullalways
      The policy file at https://mta-sts.<domain>/.well-known/mta-sts.txt.
      Show 5 fields

      • statusstringalways
        ok, missing, redirect (not allowed), invalid or error (our fetch failed).

        one of "ok", "missing", "redirect", "invalid", "error"

      • modestring or nullalways
        enforce, testing or none.

        one of "enforce", "testing", "none", null

      • maxAgeinteger or nullalways
        max_age, in seconds.
      • mxarray of stringsalways
        The mx: patterns.
      • httpStatusinteger or nullalways
        The HTTP status when the file couldn't be read.
  • tlsRptstring or nullalways
    The TLS-RPT record (RFC 8460); null when none.
  • bimistring or nullalways
    The default BIMI record; null when none.
  • danearray of objectsalways
    DANE per mail server: TLSA records at _25._tcp.<host>.
    Show 4 fields

    • hoststringalways
      The mail server.
    • tlsaarray of stringsalways
      Its TLSA records.
    • dnssecValidatedbooleanalways
      The TLSA answer validated with DNSSEC: DANE in force.
    • statusstringalways
      ok, none or error.

      one of "ok", "none", "error"

  • dnssecstringalways
    The domain's DNSSEC: secure (validated), unsigned, broken (fails validation) or unknown.

    one of "secure", "unsigned", "broken", "unknown"

  • dsarray of stringsalways
    The zone's DS records at the parent.
  • autodiscoverstring or nullalways
    autodiscover.<domain>'s CNAME target (Outlook's names Microsoft 365).
• sourcesarray of objectsalways
  Each source's MX answer: the zone's own nameservers, Google and Cloudflare (TTLs are the time left in the resolvers' caches).
  Show 9 fields

  • sourcestringalways
    Who answered: authoritative (the zone's own nameserver, the fresh truth), google (Google Public DNS's cached copy) or cloudflare (Cloudflare 1.1.1.1's).

    one of "authoritative", "google", "cloudflare"

  • serverstring or nullalways
    The server asked.
  • ipstring or nullalways
    Its address.
  • statusstringalways
    Its answer: ok (records came back), nodata (the name exists without them), nxdomain (no such name), servfail, refused, timeout, error or unreadable (an answer our decoder refuses).

    one of "ok", "nodata", "nxdomain", "servfail", "refused", "timeout", "error", "unreadable"

  • unavailablestringoptional
    Only when the zone's own servers gave no answer: blocked (on Cloudflare's network), ipv6 (IPv6-only servers), timeout, error, nxdomain or nopath.

    one of "blocked", "ipv6", "timeout", "error", "nxdomain", "nopath"

  • viaCloudflarebooleanalways
    Read through 1.1.1.1 (a zone on Cloudflare's nameservers).
  • recordsarray of objectsalways
    Its MX records.
    Show 3 fields

    • priorityintegeralways
      Lower is tried first; equal numbers share the load.
    • hoststringalways
      The mail server; . is a null MX.
    • ttlintegeralways
      The record's TTL, in seconds.
  • tookMsintegeralways
    How long that answer took, in milliseconds.
  • sameAsAuthoritativeboolean or nullalways
    The copy holds the same records as the zone's own answer; null for the zone's own, or when either is missing.
• issuesarray of objectsalways
  Problems found in the target's configuration, worst first. Empty when there are none.
  • severitystringalways
    error breaks something, warning risks it, info is worth knowing.

    one of "error", "warning", "info"

  • codestringalways
    Stable machine-readable code.
  • messagestringalways
    The problem and what to do about it, in plain English.

Errors

Plus the errors every endpoint can return: 400 for a missing or unreadable parameter, 429 past the limit, 503 when every source failed.