# Domain and lookup tools

Source: https://docs.rocketverifier.com/api/domain
Endpoint: `GET https://api.rocketverifier.com/v1/tools/mx-lookup`

> 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:

```bash
curl "https://api.rocketverifier.com/v1/tools/mx-lookup?domain=northwind.io"
```

Node.js:

```js
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);
```

Python:

```python
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)
```

Response 200:

```json
{
  "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.

## 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](https://docs.rocketverifier.com/rate-limits) 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**

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string | A domain, or an address whose domain is looked up. required |

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string |  |
| `has_mx` | boolean | True when the domain publishes MX records. |
| `mx_records` | array of objects |  |
| `mx_records.priority` | integer | MX preference. Lower is tried first. |
| `mx_records.host` | string |  |
| `primary_mx` | string 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:

```bash
curl "https://api.rocketverifier.com/v1/tools/disposable-check?email=jo@mailinator.com"
```

Response 200:

```json
{
  "email": "jo@mailinator.com",
  "domain": "mailinator.com",
  "is_disposable": true,
  "provider_hint": "disposable"
}
```

**Query parameters**

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | An address. Its domain is checked. Takes precedence over `domain`. |
| `domain` | string | A domain to check. |

| Field | Type | Description |
| --- | --- | --- |
| `email` | string or null | The address you sent, if any. |
| `domain` | string | The domain that was checked. |
| `is_disposable` | boolean |  |
| `provider_hint` | string 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:

```bash
curl "https://api.rocketverifier.com/v1/tools/domain-auth?domain=northwind.io"
```

Response 200:

```json
{
  "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](https://docs.rocketverifier.com/api/monitors).

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string |  |
| `spf` | object |  |
| `spf.status` | enum | one of `pass`, `missing` |
| `spf.record` | string or null | The `v=spf1` TXT record. |
| `dmarc` | object |  |
| `dmarc.status` | enum | one of `pass`, `missing` |
| `dmarc.record` | string or null | The `v=DMARC1` record at `_dmarc.<domain>`. |
| `dkim` | object |  |
| `dkim.status` | enum | one of `pass`, `missing` |
| `dkim.selectors` | array of strings | Selectors with a published DKIM key. |
| `score` | integer | SPF 35, DMARC 35, DKIM 30. 0 to 100 |
| `recommendations` | array 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**

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string | A domain, or an address whose domain is checked. Send `domain` or `ip`. |
| `ip` | string | A public IPv4 address to check instead of a domain. |

cURL:

```bash
curl "https://api.rocketverifier.com/v1/tools/blacklist-monitor?domain=northwind.io"
```

Response 200:

```json
{
  "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.

| Field | Type | Description |
| --- | --- | --- |
| `domain` | string or null | The checked domain. Null when an `ip` was checked. |
| `ip` | string or null | The checked IPv4 address. Null when a domain was checked. |
| `listed` | boolean | True when any checked IP is listed. |
| `lists_checked` | array of strings | The DNS blacklists queried, such as `zen.spamhaus.org` and `bl.spamcop.net`. |
| `checked_ips` | array of strings | The mail server IPv4 addresses that were checked. |
| `listings` | array of objects | Every listing found. |
| `listings.ip` | string |  |
| `listings.blacklist` | string |  |
| `not_checked` | array of objects | IP and list pairs where the list refused the query or did not answer. |
| `not_checked.ip` | string |  |
| `not_checked.blacklist` | string |  |
| `details` | array of objects | One row per list. |
| `details.list` | string |  |
| `details.zone` | string |  |
| `details.type` | enum | one of `ip` |
| `details.listed` | boolean |  |
| `details.listed_ips` | array of strings |  |
| `details.not_checked_ips` | array of strings | Present only when the list did not answer for some IPs. |
| `error` | string 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:

```bash
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:

```json
{
  "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`](https://docs.rocketverifier.com/api/verify) or the [sandbox](https://docs.rocketverifier.com/sandbox) for free tests.

**Body**

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The address to look up. required |
| `turnstile_token` | string 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:

```bash
curl https://api.rocketverifier.com/v1/tools/activity/maya@northwind.io \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Response 200:

```json
{
  "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](https://docs.rocketverifier.com/api/verify#response).

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The address, trimmed and lowercased. |
| `verification_count` | integer | Your verifications of this address in the last 90 days (up to 50). |
| `activity_score` | integer | 10 points per verification, capped at 100. 0 to 100 |
| `stability_score` | integer | Share of those verifications that returned the most common classification. 100 with one or no verification. 0 to 100 |
| `last_seen_at` | integer or null | Unix time of your latest verification of this address. |
| `classifications` | object | 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](https://docs.rocketverifier.com/api#handle-errors).

## 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.
