Name: Email Validator API: MX, Disposable and Typo Checks
Brand: compasslab-1
SKU: api-compasslab-1-email-validator
Availability: InStock
Author: API Market

WPTOOLS

# Email Validator API

## Overview

The Email Validator API checks an email address before you store it or send to it. It checks the syntax against RFC 5322, including international addresses, looks up the domain's MX records to see whether it can receive mail, and flags disposable or throwaway providers, role accounts such as info@ and support@, and free consumer providers. When the domain looks like a typo of a common one, such as gmial.com, it suggests the corrected address. It has 2 endpoints. The single endpoint validates one address per call, and the batch endpoint runs the same checks on up to 10 addresses, looks each domain up only once, and returns the results in input order with a count per verdict.

It is built for developers adding validation to signup, checkout and lead forms, CRM and marketing teams keeping junk and throwaway addresses out of their lists, and B2B teams that want to separate company domains from consumer mailboxes. Each result has one verdict in `status` (`valid`, `invalid`, `risky` or `unknown`), a `reasons` list that explains any verdict other than `valid`, and every individual flag (`syntax_valid`, `disposable`, `role_account`, `free_provider`, `mx_found`) so you can apply your own rules. It also returns the normalised address, its local part and domain, a `did_you_mean` suggestion and the domain's mail servers by priority. No email is sent and no mail server is contacted.

## Features

*   **2 endpoints**: Single-address validation and a batch endpoint for up to 10 addresses per call, where a batch counts as one request.
*   **Simple inputs**: One email address (up to 320 characters) as a query parameter, or a JSON list of 1 to 10 addresses, with an optional switch to skip the DNS lookup.
*   **Syntax check**: RFC 5322 syntax, including international addresses with non-ASCII local parts and domains, with a readable `syntax_error` when it fails.
*   **MX lookup**: Whether the domain accepts mail according to DNS, with its mail servers and their priorities.
*   **Risk flags**: Disposable providers (subdomains included), role accounts and free consumer providers such as Gmail, Outlook and GMX.
*   **Typo suggestions**: A `did_you_mean` address for likely misspellings of common domains.
*   **Data source and method**: Syntax rules, provider lists and live DNS lookups. No SMTP connection is made, so the API does not confirm that a specific mailbox exists.
*   **Rate limit**: 1 request per second on FREE and PRO, 10 on ULTRA and 20 on MEGA.

## Use Cases

*   **Signup and checkout forms**: Catch typos like gmial.com and show the suggested address before the user leaves the page.
*   **Lead forms and CRMs**: Keep disposable and invalid addresses out of your lead database.
*   **List cleaning**: Check a mailing list in batches of 10 before a campaign to remove addresses whose domains cannot receive mail.
*   **B2B lead scoring**: Use `free_provider` to separate consumer mailboxes from company domains.
*   **Role account handling**: Use `role_account` to route shared mailboxes such as support@ differently from personal ones.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/compasslab-1/email-validator
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate one email

Checks the syntax of one address, looks up the domain's MX records (unless `check_dns=false`), and flags disposable providers, role accounts and free providers, with a typo suggestion for misspelled common domains. `status` is the verdict: `valid`, `invalid`, `risky` or `unknown`.

**Method:** `GET`

**Endpoint:** `/v1/email/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `email` | query | The email address to check. URL-encode it (`@` becomes `%40`). | string | Yes | - | 320 characters |
| `check_dns` | query | Look up MX records. Set to `false` for syntax and list checks only, which is faster. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/compasslab-1/email-validator/v1/email/validate?email=support%40github.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "input": "support@github.com",
  "email": "support@github.com",
  "local_part": "support",
  "domain": "github.com",
  "status": "valid",
  "reasons": [],
  "syntax_valid": true,
  "syntax_error": null,
  "disposable": false,
  "role_account": true,
  "free_provider": false,
  "did_you_mean": null,
  "mx_found": true,
  "mx": [
    {
      "host": "github-com.mail.protection.outlook.com",
      "priority": 0
    }
  ]
}
```

The address is `valid` and `role_account` is `true` because support@ is a shared mailbox. Role accounts are flagged, not rejected.

#### 2. Validate a batch of emails

Runs the same checks as the single endpoint on up to 10 addresses. Each domain is looked up once, even when several addresses share it. Results come back in input order, with a `summary` that counts each verdict. A batch counts as one request.

**Method:** `POST`

**Endpoint:** `/v1/email/validate/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `emails` | body | List of 1 to 10 email addresses. Split larger lists into several calls. | array of strings | Yes | - | 10 items |
| `check_dns` | body | Look up MX records for each domain. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/compasslab-1/email-validator/v1/email/validate/batch" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["hello@api.market", "user@mailinator.com", "test@gmial.com"]}'
```

**Example Response (200 OK):**

```json
{
  "count": 3,
  "summary": {
    "valid": 1,
    "invalid": 0,
    "risky": 2,
    "unknown": 0
  },
  "results": [
    {
      "input": "hello@api.market",
      "email": "hello@api.market",
      "local_part": "hello",
      "domain": "api.market",
      "status": "valid",
      "reasons": [],
      "syntax_valid": true,
      "syntax_error": null,
      "disposable": false,
      "role_account": true,
      "free_provider": false,
      "did_you_mean": null,
      "mx_found": true,
      "mx": [
        {
          "host": "aspmx.l.google.com",
          "priority": 1
        },
        {
          "host": "alt1.aspmx.l.google.com",
          "priority": 5
        },
        {
          "host": "alt2.aspmx.l.google.com",
          "priority": 5
        },
        {
          "host": "alt3.aspmx.l.google.com",
          "priority": 10
        },
        {
          "host": "alt4.aspmx.l.google.com",
          "priority": 10
        }
      ]
    },
    {
      "input": "user@mailinator.com",
      "email": "user@mailinator.com",
      "local_part": "user",
      "domain": "mailinator.com",
      "status": "risky",
      "reasons": [
        "disposable"
      ],
      "syntax_valid": true,
      "syntax_error": null,
      "disposable": true,
      "role_account": false,
      "free_provider": false,
      "did_you_mean": null,
      "mx_found": true,
      "mx": [
        {
          "host": "mail.mailinator.com",
          "priority": 1
        },
        {
          "host": "mail2.mailinator.com",
          "priority": 1
        }
      ]
    },
    {
      "input": "test@gmial.com",
      "email": "test@gmial.com",
      "local_part": "test",
      "domain": "gmial.com",
      "status": "risky",
      "reasons": [
        "disposable"
      ],
      "syntax_valid": true,
      "syntax_error": null,
      "disposable": true,
      "role_account": false,
      "free_provider": false,
      "did_you_mean": "test@gmail.com",
      "mx_found": true,
      "mx": []
    }
  ]
}
```

In this example `user@mailinator.com` is `risky` because mailinator.com is a disposable provider, and `test@gmial.com` is also flagged as disposable and comes with the suggestion `test@gmail.com` in `did_you_mean`.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The address or batch was checked. The verdict is in `status` for each result, so an `invalid` or `risky` address still returns `200`. |
| 400 | Bad Request | The request is malformed and could not be processed. Check the URL encoding of `email` and the JSON body of a batch call. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API, for example a typo in `/v1/email/validate`. |
| 422 | Unprocessable Entity | A parameter is missing or invalid, such as a missing `email`, an empty `emails` list or more than 10 addresses in a batch. The `detail` field says which one. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Each plan has its own per-second limit: FREE and PRO allow 1 request per second, ULTRA 10 and MEGA 20. The plans include 100, 5,000, 25,000 and 100,000 calls respectively, and a batch of up to 10 addresses counts as one call, so batching is the way to check more addresses per second on FREE and PRO. Requests above the per-second limit, or after the plan's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. The seller reports about 70 ms per address in its own tests. Setting `check_dns=false` skips the DNS lookup and is faster.

## FAQ

**Does `valid` mean the mailbox exists?**

No. It means the address is well formed and its domain accepts mail. The API never contacts mail servers and sends no email, so it cannot confirm that a specific mailbox exists.

**What does `risky` mean?**

The domain is a known disposable or throwaway inbox provider, such as mailinator.com. Subdomains of those providers are flagged too. The `reasons` list contains `disposable`.

**What does `unknown` mean?**

DNS did not answer in time, so the API could not tell whether the domain accepts mail. Retry the address later.

**Are role addresses like info@ blocked?**

No. They are returned as `valid` with `role_account` set to `true`, so you can decide how to handle them.

**Why is `mx` empty when `mx_found` is `true`?**

Some domains have no MX record and receive mail through their A record instead (implicit MX). In that case `mx_found` is `true` and the `mx` list is empty. `mx_found` is `null` when `check_dns=false` or the syntax is invalid.

**Are international addresses supported?**

Yes. Addresses with non-ASCII local parts and domains are checked, and the domain is looked up in its punycode form. The normalised `email` field shows the domain lower-cased, with internationalised domains in Unicode.

**How do I check more than 10 addresses?**

Split the list into batches of 10 and send one batch call per group. Each batch counts as one request against your plan's calls and per-second limit.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Email Validator API checks syntax, MX records, disposable and role addresses, free providers and typos, and returns a valid, invalid or risky verdict.

Email Validator API: MX, Disposable and Typo Checks

FREE