https://api.rocketverifier.com/v1/tools/mx-lookupDomain 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"import RocketVerifier from "@rocketverifier/sdk";
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
// MX lookup and disposable check in one call
const domain = await rv.domain.check("northwind.io");
console.log(domain.hasValidMx, domain.mxRecords, domain.disposable);import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
# MX lookup and disposable check in one call
domain = rv.domain.check("northwind.io")
print(domain.has_valid_mx, domain.mx_records, domain.disposable){
"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
A domain, or an address whose domain is looked up.
- domainstring
- has_mxboolean
True when the domain publishes MX records.
- mx_recordsarray of objects
- 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.
/v1/tools/disposable-checkcurl "https://api.rocketverifier.com/v1/tools/disposable-check?email=jo@mailinator.com"{
"email": "jo@mailinator.com",
"domain": "mailinator.com",
"is_disposable": true,
"provider_hint": "disposable"
}Query parameters
- emailstring or null
The address you sent, if any.
- domainstring
The domain that was checked.
- is_disposableboolean
- provider_hintstring or null
disposablewhen 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.
/v1/tools/domain-authcurl "https://api.rocketverifier.com/v1/tools/domain-auth?domain=northwind.io"{
"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
- dmarcobject
- dkimobject
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.
/v1/tools/blacklist-monitorQuery parameters
curl "https://api.rocketverifier.com/v1/tools/blacklist-monitor?domain=northwind.io"{
"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
ipwas 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.organdbl.spamcop.net. - checked_ipsarray of strings
The mail server IPv4 addresses that were checked.
- listingsarray of objects
Every listing found.
- not_checkedarray of objects
IP and list pairs where the list refused the query or did not answer.
- detailsarray of objects
One row per list.
› Show 6 child fields
- liststring
- zonestring
- typeenumip
- listedboolean
- listed_ipsarray of strings
- not_checked_ipsarray of strings
Present only when the list did not answer for some IPs.
- 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.
/v1/tools/verify-freecurl -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"}'{
"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
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.
/v1/tools/activity/{email}curl https://api.rocketverifier.com/v1/tools/activity/maya@northwind.io \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"{
"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.
- verification_countinteger
Your verifications of this address in the last 90 days (up to 50).
10 points per verification, capped at 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.
- classificationsobject
Count per classification.
Errors#
| Status | error.code | When it happens |
|---|---|---|
| 400 | missing_input | The disposable check got neither email nor domain. |
| 400 | invalid_domain | The blacklist check got something that is not a domain. |
| 400 | invalid_ip | The blacklist check got an IP that is not a public IPv4 address. |
| 400 | invalid_email | The free test lookup got an address with invalid syntax. |
| 401 | unauthorized | Activity history was called without a valid key. |
| 403 | captcha_failed | The free test lookup was called without a valid key or Turnstile token. |
| 422 | validation_error | A required parameter such as domain is missing. |
| 429 | rate_limited | More than 5 anonymous requests per minute from this IP, or your account's limit. |
| 429 | daily_limit_reached | The free test lookup's 2 lookups per IP per day are used. |
| 503 | service_unavailable | The 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