Name: Email Validation API: MX, Disposable and Typo Check
Brand: leadharbor
SKU: api-leadharbor-email-validation-triage
Availability: InStock
Author: API Market

Mohammed Samaan

# Email Validation and Triage API

## Overview

The Email Validation and Triage API checks an email address before you store it or send to it, and answers with a verdict instead of a score. It has 2 endpoints on the same path. A `GET` request checks one address, and a `POST` request checks up to 25 addresses in one call and returns the same result object for each of them. Every check looks at the address syntax, whether the domain can receive mail (MX records, with the standard fallback to an A or AAAA record when there is no MX, and detection of a null MX), whether the domain is on a list of 8,833 known disposable email providers, whether the address is a role address such as `info@` or `support@`, whether it uses a free consumer provider, whether it carries a plus-tag, and whether the domain looks like a near-miss typo of a large provider.

It is built for sign-up forms, CRMs, lead capture tools and email marketing teams that want to stop bad addresses at the door and flag doubtful ones for a person to look at. Each result carries a `verdict` (`accept`, `review`, `reject` or `retry`), a list of `reason_codes` that explain it, the domain in Unicode and ASCII form, the `base_email` with any plus-tag removed, a `typo_suggestion` when the domain looks mistyped, and the `mx_hosts` that were found. The mailbox itself is never contacted, so `mailbox_checked` is always `false`: an `accept` means the domain can receive mail and nothing about the address looked wrong, not that the mailbox exists.

## Features

*   **2 endpoints**: Triage one address with `GET`, or up to 25 addresses with `POST`.
*   **Simple inputs**: One `email` query parameter, or a JSON body with an `emails` array.
*   **Verdicts with reasons**: Each address gets `accept`, `review`, `reject` or `retry`, plus reason codes such as `MX_FOUND`, `ROLE_ADDRESS`, `DISPOSABLE_DOMAIN` and `TYPO_SUSPECTED`.
*   **Mail server check**: Looks up MX records over DNS, falls back to A or AAAA records as the email standards allow, and recognises a null MX that says the domain accepts no mail.
*   **Disposable domain list**: Flags addresses on 8,833 known disposable email providers.
*   **Typo suggestions**: Near-miss domains of big providers return a corrected address in `typo_suggestion`. The input is never changed for you.
*   **Plus-tag handling**: `base_email` gives the address with any `+tag` removed, so you can find duplicates.
*   **No mailbox probing**: The API never connects to the mail server to test the mailbox, so checks do not touch the recipient. A DNS timeout returns `retry`, never `reject`.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **Sign-up forms**: Block disposable addresses and offer "did you mean" suggestions before an account is created.
*   **Lead capture**: Tag role addresses such as `sales@` or `support@` for review instead of assigning them to a sales rep.
*   **List cleaning**: Run an existing contact list through the batch endpoint 25 addresses at a time and remove the `reject` results before a campaign.
*   **CRM hygiene**: Use `base_email` to merge contacts that signed up with different plus-tags.
*   **Fraud and abuse screening**: Treat disposable domains and domains with no mail server as a signal in your trust checks.
*   **Data entry checks**: Catch mistyped domains such as `gmial.com` in support or sales tools while the customer is still on the line.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/leadharbor/email-validation-triage
```

### 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. Triage one email address

Checks a single address and returns its verdict, reason codes, domain, base address, typo suggestion and mail servers. Remember to URL-encode the `@` as `%40` if your HTTP client does not do it for you.

**Method:** `GET`

**Endpoint:** `/v1/market/email-triage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `email` | query | The email address to check, for example `jane@gmial.com`. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/email-validation-triage/v1/market/email-triage?email=jane%40gmial.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "email": "jane@gmial.com",
  "verdict": "reject",
  "reason_codes": [
    "DISPOSABLE_DOMAIN",
    "TYPO_SUSPECTED"
  ],
  "mailbox_checked": false,
  "domain": "gmial.com",
  "domain_ascii": "gmial.com",
  "base_email": "jane@gmial.com",
  "typo_suggestion": "jane@gmail.com",
  "mx_hosts": [],
  "meta": {
    "user": null
  }
}
```

A role address on a domain with a working mail server comes back as `review` instead:

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

**Example Response (200 OK):**

```json
{
  "email": "support@github.com",
  "verdict": "review",
  "reason_codes": [
    "MX_FOUND",
    "ROLE_ADDRESS"
  ],
  "mailbox_checked": false,
  "domain": "github.com",
  "domain_ascii": "github.com",
  "base_email": "support@github.com",
  "typo_suggestion": null,
  "mx_hosts": [
    "github-com.mail.protection.outlook.com"
  ],
  "meta": {
    "user": null
  }
}
```

**Response fields:**

*   **`email`**: The address you sent.
*   **`verdict`**: `accept`, `review`, `reject` or `retry`. `retry` means a DNS lookup timed out, so try again later.
*   **`reason_codes`**: The findings behind the verdict, for example `MX_FOUND`, `ROLE_ADDRESS`, `DISPOSABLE_DOMAIN` and `TYPO_SUSPECTED`.
*   **`mailbox_checked`**: Always `false`. The mailbox is never contacted.
*   **`domain`** and **`domain_ascii`**: The domain part of the address, as written and in ASCII (Punycode) form for internationalised domains.
*   **`base_email`**: The address with any plus-tag removed.
*   **`typo_suggestion`**: A suggested corrected address when the domain looks like a typo of a large provider, otherwise `null`.
*   **`mx_hosts`**: The mail servers found for the domain. Empty when none were found.
*   **`meta`**: Metadata you can ignore. `user` is always `null`.

#### 2. Triage up to 25 email addresses

Checks a list of addresses in one request and returns one result per address, in the order you sent them. Each result has the same fields as the single-address endpoint. Sending more than 25 addresses returns `400`.

**Method:** `POST`

**Endpoint:** `/v1/market/email-triage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `emails` | body | Array of email addresses to check. | array of strings | Yes | - | 25 items |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/leadharbor/email-validation-triage/v1/market/email-triage" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["jane@gmial.com", "support@github.com", "test@mailinator.com"]}'
```

**Example Response (200 OK):**

```json
{
  "results": [
    {
      "email": "jane@gmial.com",
      "verdict": "reject",
      "reason_codes": [
        "DISPOSABLE_DOMAIN",
        "TYPO_SUSPECTED"
      ],
      "mailbox_checked": false,
      "domain": "gmial.com",
      "domain_ascii": "gmial.com",
      "base_email": "jane@gmial.com",
      "typo_suggestion": "jane@gmail.com",
      "mx_hosts": []
    },
    {
      "email": "support@github.com",
      "verdict": "review",
      "reason_codes": [
        "MX_FOUND",
        "ROLE_ADDRESS"
      ],
      "mailbox_checked": false,
      "domain": "github.com",
      "domain_ascii": "github.com",
      "base_email": "support@github.com",
      "typo_suggestion": null,
      "mx_hosts": [
        "github-com.mail.protection.outlook.com"
      ]
    },
    {
      "email": "test@mailinator.com",
      "verdict": "reject",
      "reason_codes": [
        "DISPOSABLE_DOMAIN"
      ],
      "mailbox_checked": false,
      "domain": "mailinator.com",
      "domain_ascii": "mailinator.com",
      "base_email": "test@mailinator.com",
      "typo_suggestion": null,
      "mx_hosts": []
    }
  ],
  "meta": {
    "count": 3,
    "user": null
  }
}
```

`results` holds one object per address, and `meta.count` is the number of addresses checked. `meta.user` is metadata you can ignore.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The addresses were checked. A `reject` or `review` verdict is still a successful response. |
| 400 | Bad Request | The `email` parameter is missing, the `emails` body is missing, or the batch has more than 25 addresses. |
| 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 is wrong. Check that it is `/v1/market/email-triage`. |
| 429 | Too Many Requests | You went over 10 requests per second, 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

The Free trial, Starter and PAYG plans each allow 10 requests per second. The Free trial includes 500 calls and the Starter plan 10,000 calls, with extra Starter calls billed at $0.001 each. PAYG has no subscription and costs $0.001 per call. Requests above the per-second limit, or after a plan's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which gives the number of seconds to wait. For large lists, use the batch endpoint to check 25 addresses per request instead of sending one request per address. In our tests a single check answered in about 0.5 seconds and a batch of 3 in about 0.65 seconds.

## FAQ

**Does an `accept` verdict mean the email will be delivered?**

No. The API never contacts the mailbox, so it cannot tell whether a specific mailbox exists or will accept a message. `accept` means the address is well formed, the domain can receive mail and nothing else looked wrong. `mailbox_checked` is always `false` to make this clear.

**What is the difference between `review` and `reject`?**

`reject` is for addresses you should not store or send to, such as addresses on known disposable domains. `review` is for addresses that are valid but worth a second look, such as role addresses like `support@` that reach a team instead of a person. Read `reason_codes` to see exactly what was found and set your own rules.

**What should I do with a `retry` verdict?**

`retry` means a DNS lookup timed out, so the API could not decide. It is never turned into a `reject`. Check the address again a little later.

**Does the API fix typos for me?**

No. When a domain looks like a near-miss of a large provider, for example `gmial.com`, the result includes `TYPO_SUSPECTED` and a corrected address in `typo_suggestion`. The input is left as it is, so you can show the suggestion to the user and let them choose.

**How many addresses can I check in one request?**

Up to 25 with the `POST` endpoint. Larger lists need to be split into chunks of 25, and more than 25 in one request returns `400`.

**What does `base_email` do?**

It returns the address without any plus-tag, so `jane+news@example.com` and `jane@example.com` share the same `base_email`. Use it to spot the same person signing up more than once.

**Do I need any other key to use the API?**

No. Your API.market key in the `x-api-market-key` header is all you need.

## 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 validation API that checks syntax, MX records, disposable domains, role addresses and typos, and returns a verdict with reason codes. Bulk up to 25.

Email Validation API: MX, Disposable and Typo Check

Free trial