Skip to content
RocketVerifierDOCS
GEThttps://api.rocketverifier.com/v1/tools/mx-lookup

Domain and lookup tools

In short

The /v1/tools endpoints answer DNS-level questions about a domain for free, with no verification credits. Look up MX records, detect disposable domains, score SPF, DKIM and DMARC, and check DNS blacklists. They work without a key at 5 requests per minute per IP, or at your account's rate limit with one.

curl "https://api.rocketverifier.com/v1/tools/mx-lookup?domain=northwind.io"
Response 200
{
  "domain": "northwind.io",
  "has_mx": true,
  "mx_records": [
    { "priority": 1, "host": "aspmx.l.google.com" },
    { "priority": 5, "host": "alt1.aspmx.l.google.com" }
  ],
  "primary_mx": "aspmx.l.google.com"
}

The lookup tools answer questions about a domain from DNS and blocklists, in one fast request and without spending credits. They power the free tools on rocketverifier.com and the MCP server, and they are open to your code too.

Cost
Free
Key
Optional
Without a key
5 per minute per IP
Mailbox check
Use /v1/verify

Call the tools with or without a key#

Every tool except activity history works without a key. Anonymous calls are limited to 5 requests per minute per IP address. Send Authorization: Bearer <key> to use your account's rate limit instead. Anonymous calls are refused with 503 service_unavailable in the rare moment the rate limiter is unreachable, so retry after a short wait.

Every tool accepts a domain or a full address. With an address, the domain after the @ is used.

Look up MX records#

GET /v1/tools/mx-lookup returns a domain's MX records in priority order and its primary mail server. A POST variant takes the same domain query parameter.

Query parameters

  • domainstringrequired

    A domain, or an address whose domain is looked up.

  • domainstring
  • has_mxboolean

    True when the domain publishes MX records.

  • mx_recordsarray of objects
    › Show 2 child fields
    • priorityinteger

      MX preference. Lower is tried first.

    • hoststring
  • primary_mxstring or null

    The highest priority MX host.

Check for disposable domains#

GET /v1/tools/disposable-check says whether a domain or address belongs to a disposable inbox provider, from a continuously updated database of tens of thousands of disposable domains. POST takes the same fields as a JSON body.

GET/v1/tools/disposable-check
cURL
curl "https://api.rocketverifier.com/v1/tools/disposable-check?email=jo@mailinator.com"
Response 200
{
  "email": "jo@mailinator.com",
  "domain": "mailinator.com",
  "is_disposable": true,
  "provider_hint": "disposable"
}

Query parameters

  • emailstring

    An address. Its domain is checked. Takes precedence over domain.

  • domainstring

    A domain to check.

  • emailstring or null

    The address you sent, if any.

  • domainstring

    The domain that was checked.

  • provider_hintstring or null

    disposable when the domain is disposable, otherwise null.

A request with neither email nor domain returns 400 missing_input.

Check SPF, DKIM and DMARC#

GET /v1/tools/domain-auth reads a domain's SPF, DMARC and DKIM records, scores them from 0 to 100 and returns one fix per missing record.

GET/v1/tools/domain-auth
cURL
curl "https://api.rocketverifier.com/v1/tools/domain-auth?domain=northwind.io"
Response 200
{
  "domain": "northwind.io",
  "spf": { "status": "pass", "record": "v=spf1 include:_spf.google.com ~all" },
  "dmarc": { "status": "missing", "record": null },
  "dkim": { "status": "pass", "selectors": ["google"] },
  "score": 65,
  "recommendations": ["Publish a DMARC policy at _dmarc.{domain}."]
}

The score adds 35 points for SPF, 35 for DMARC and 30 for DKIM. DKIM is found on the selectors default, google, selector1, selector2, k1, s1 and mail, so a key on another selector reads as missing. To watch these records over time and get alerted when one disappears, create a domain authentication monitor.

  • domainstring
  • spfobject
    › Show 2 child fields
    • statusenum
      passmissing
    • recordstring or null

      The v=spf1 TXT record.

  • dmarcobject
    › Show 2 child fields
    • statusenum
      passmissing
    • recordstring or null

      The v=DMARC1 record at _dmarc.<domain>.

  • dkimobject
    › Show 2 child fields
    • statusenum
      passmissing
    • selectorsarray of strings

      Selectors with a published DKIM key.

  • scoreinteger0 to 100

    SPF 35, DMARC 35, DKIM 30.

  • recommendationsarray of strings

    One fix per missing record.

Check DNS blacklists#

GET /v1/tools/blacklist-monitor checks a domain's mail servers, or one IPv4 address, against DNS blacklists. With domain, up to 5 MX hosts (or the domain itself when it has no MX) are resolved to IPv4 addresses and each one is checked.

GET/v1/tools/blacklist-monitor

Query parameters

  • domainstring

    A domain, or an address whose domain is checked. Send domain or ip.

  • ipstring

    A public IPv4 address to check instead of a domain.

cURL
curl "https://api.rocketverifier.com/v1/tools/blacklist-monitor?domain=northwind.io"
Response 200
{
  "domain": "northwind.io",
  "ip": null,
  "listed": false,
  "lists_checked": ["zen.spamhaus.org", "bl.spamcop.net"],
  "details": [
    { "list": "zen.spamhaus.org", "zone": "zen.spamhaus.org", "type": "ip", "listed": false, "listed_ips": [] },
    { "list": "bl.spamcop.net", "zone": "bl.spamcop.net", "type": "ip", "listed": false, "listed_ips": [] }
  ],
  "checked_ips": ["142.250.153.26", "142.250.153.27"],
  "listings": [],
  "not_checked": [],
  "error": null
}

Read listed for the answer and listings for each IP and list pair that matched. A list that refused the query or did not answer appears in not_checked, never as a listing, so a quiet list cannot produce a false alarm.

  • domainstring or null

    The checked domain. Null when an ip was checked.

  • ipstring or null

    The checked IPv4 address. Null when a domain was checked.

  • listedboolean

    True when any checked IP is listed.

  • lists_checkedarray of strings

    The DNS blacklists queried, such as zen.spamhaus.org and bl.spamcop.net.

  • checked_ipsarray of strings

    The mail server IPv4 addresses that were checked.

  • listingsarray of objects

    Every listing found.

    › Show 2 child fields
  • not_checkedarray of objects

    IP and list pairs where the list refused the query or did not answer.

    › Show 2 child fields
  • detailsarray of objects

    One row per list.

    › Show 6 child fields
  • errorstring or null

    Set when the domain's IPs could not be resolved.

Run a free test lookup#

POST /v1/tools/verify-free runs syntax, MX and disposable checks on one address, without a live SMTP check. It returns undeliverable for disposable addresses and domains with no MX, and unknown otherwise, because only an SMTP check can confirm a mailbox.

POST/v1/tools/verify-free
cURL
curl -X POST https://api.rocketverifier.com/v1/tools/verify-free \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "maya@northwind.io"}'
Response 200
{
  "email": "maya@northwind.io",
  "status": "unknown",
  "score": 40,
  "is_disposable": false,
  "mx_found": true
}

The response also carries a note reminding you that this is a lookup, not a mailbox check.

  • Limit: 2 lookups per IP address per day, with or without a key. The third returns 429 daily_limit_reached.
  • Captcha: calls without a valid API key must carry a Cloudflare Turnstile turnstile_token, as the website's free tool does. A valid key skips the captcha.

For real verification at scale, use POST /v1/verify or the sandbox for free tests.

Body

  • emailstringrequired

    The address to look up.

  • turnstile_tokenstring or null

    Cloudflare Turnstile token. Required without a valid API key.

Read your verification history for an address#

GET /v1/tools/activity/{email} reports how often your account has verified an address and how consistent the results were. It reads your last 50 verifications of the address over the past 90 days, and only your own: organization keys see the organization's history, and no account ever sees another's. It needs a valid API key or OAuth token, no scope and no balance.

GET/v1/tools/activity/{email}
cURL
curl https://api.rocketverifier.com/v1/tools/activity/maya@northwind.io \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
Response 200
{
  "email": "maya@northwind.io",
  "verification_count": 4,
  "activity_score": 40,
  "stability_score": 100,
  "last_seen_at": 1762853537,
  "classifications": { "valid": 4 }
}

A low stability_score means the address has changed answers over time, for example a mailbox that filled up or a domain that turned catch-all. The same scores appear in the activity object of every verify response.

  • emailstring

    The address, trimmed and lowercased.

  • Your verifications of this address in the last 90 days (up to 50).

  • activity_scoreinteger0 to 100

    10 points per verification, capped at 100.

  • stability_scoreinteger0 to 100

    Share of those verifications that returned the most common classification. 100 with one or no verification.

  • last_seen_atinteger or null

    Unix time of your latest verification of this address.

  • Count per classification.

Errors#

Statuserror.codeWhen it happens
400missing_inputThe disposable check got neither email nor domain.
400invalid_domainThe blacklist check got something that is not a domain.
400invalid_ipThe blacklist check got an IP that is not a public IPv4 address.
400invalid_emailThe free test lookup got an address with invalid syntax.
401unauthorizedActivity history was called without a valid key.
403captcha_failedThe free test lookup was called without a valid key or Turnstile token.
422validation_errorA required parameter such as domain is missing.
429rate_limitedMore than 5 anonymous requests per minute from this IP, or your account's limit.
429daily_limit_reachedThe free test lookup's 2 lookups per IP per day are used.
503service_unavailableThe limiter is briefly unreachable. Retry shortly.

Every error uses the standard error shape.

Frequently asked questions

Do the lookup tools cost credits?

No. MX lookup, disposable check, domain authentication, blacklist check, the free test lookup and activity history are all free.

Do I need an API key?

Only for activity history. The other tools work without a key at 5 requests per minute per IP address. Send your key to get your account's rate limit instead.

Do these tools verify the mailbox?

No. They read DNS and blocklists only. To confirm that a mailbox exists, use POST /v1/verify, which runs a live SMTP check.

Which blacklists does the blacklist check query?

Every list in lists_checked, such as zen.spamhaus.org and bl.spamcop.net. Lists that refuse or ignore the query are reported in not_checked and never counted as listings.

Updated 11 November 2026Suggest an edit