Name: MailForge Email Validator API: SMTP, MX, Disposable Check
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-mailforge
Availability: InStock
Author: API Market

# MailForge Email Validator API

## Overview

The MailForge Email Validator API checks an email address in one call: syntax, the domain's mail servers (MX), disposable and role addresses, common typos and a live mailbox check over SMTP with catch-all detection. `POST /v1/validate` checks one address, `POST /v1/bulk` checks up to 1,000 addresses in parallel and returns them in the same order, and `GET /v1/health` tells you the service is up.

It is built for developers of sign-up forms, lead capture, CRMs and email marketing tools who need to stop bad addresses before they cost a bounce. Every result has a `status` (valid, risky, invalid or unknown), a `reason`, a 0 to 1 `score`, the MX records, the SMTP result, `disposable` and `role_account` flags and a typo `suggestion` such as gmial.com to gmail.com, so one if-statement is enough to accept or reject an address.

## Features

*   **Three endpoints**: single validation, bulk validation of up to 1,000 addresses, and a health check.
*   **Clear verdict**: every address gets a `status`, a `reason` and a `score` between 0 and 1.
*   **MX and SMTP checks**: the MX records are returned, and with `deep: true` the mailbox is checked over SMTP, with catch-all domains flagged.
*   **Disposable and role detection**: `disposable` and `role_account` flags catch throwaway inboxes and shared addresses such as info@.
*   **Typo suggestions**: a `suggestion` field proposes the likely intended address when the domain looks mistyped.
*   **No storage**: addresses are checked in memory and not stored.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Sign-up forms**: reject mistyped and disposable addresses before an account is created.
*   **Lead capture**: score incoming leads and keep sales from chasing dead inboxes.
*   **List cleaning**: run an existing mailing list through `/v1/bulk` before a campaign to cut bounces.
*   **Free trial abuse**: block throwaway inboxes from claiming repeated trials.
*   **CRM hygiene**: check addresses as they are imported or edited.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/hybrid-forge-lab/mailforge
```

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

Returns `ok`, the service version and its uptime. Use it for monitoring; it does not validate anything.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/mailforge/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "1.2.1",
  "uptime_s": 0
}
```

#### 2. Validate one address

Checks a single address and returns its status, reason, score, MX records, SMTP result, disposable and role flags and a typo suggestion. The example shows a mistyped Gmail domain.

**Method:** `POST`

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

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `email` | body | The email address to check. | string | Yes | - | - |
| `timeout_ms` | body | How long the SMTP check may take, in milliseconds. | integer | No | `4000` | 10000 |
| `deep` | body | Set to `true` to check the mailbox over SMTP, or `false` for syntax, MX, disposable and role checks only. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/mailforge/v1/validate' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "jane@gmial.com",
  "timeout_ms": 4000,
  "deep": true
}'
```

**Example Response (200 OK):**

```json
{
  "email": "jane@gmial.com",
  "status": "invalid",
  "reason": "no_mx",
  "mx": {
    "has_mx": false,
    "records": []
  },
  "smtp": {
    "checked": false,
    "accepts_mail": null,
    "catch_all": null
  },
  "disposable": false,
  "role_account": false,
  "suggestion": "jane@gmail.com",
  "score": 0.0,
  "duration_ms": 88,
  "request_id": "req_5bdb7e348f"
}
```

#### 3. Validate many addresses

Checks a list of addresses in parallel and returns a JSON array with one result per address, in the order you sent them. Each result has the same fields as `/v1/validate`.

**Method:** `POST`

**Endpoint:** `/v1/bulk`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `emails` | body | The addresses to check, up to 1,000 per request. | array of strings | Yes | - | 1000 items |
| `parallel` | body | How many addresses are checked at the same time. | integer | No | `4` | 16 |
| `deep` | body | Set to `true` to check each mailbox over SMTP. | boolean | No | `true` | - |
| `timeout_ms` | body | How long each SMTP check may take, in milliseconds. | integer | No | `4000` | 10000 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/mailforge/v1/bulk' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "jane@gmial.com",
    "hello@magicapi.com",
    "test@mailinator.com"
  ],
  "parallel": 4,
  "deep": true,
  "timeout_ms": 4000
}'
```

**Example Response (200 OK):**

```json
[
  {
    "email": "jane@gmial.com",
    "status": "invalid",
    "reason": "no_mx",
    "mx": {
      "has_mx": false,
      "records": []
    },
    "smtp": {
      "checked": false,
      "accepts_mail": null,
      "catch_all": null
    },
    "disposable": false,
    "role_account": false,
    "suggestion": "jane@gmail.com",
    "score": 0.0,
    "duration_ms": 140,
    "request_id": "req_b9b0d99fb3"
  }
]
```

This endpoint is available on the Pro, Ultra and pay-as-you-go plans, not on Free.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The check ran. The body has the result (or an array of results for `/v1/bulk`). An undeliverable address is still a 200 with `status` set to `invalid`. |
| 400 | Bad Request | The JSON body is malformed, `email` or `emails` is missing, or a value has the wrong type. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong. This API has `GET /v1/health`, `POST /v1/validate` and `POST /v1/bulk`. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Wait for the time in `Retry-After` and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |
| 503 | Service Unavailable | The service is briefly unavailable. Retry after a short pause. |

## Rate Limits

Every plan allows up to 10 requests per second. Monthly quotas are 15 calls on Free (a 7-day trial), 20,000 on Pro and 100,000 on Ultra, and the pay-as-you-go plan is billed per call, and each request counts as one call whatever it returns. A `/v1/bulk` request counts as one call. A deep check usually answers in 1 to 3 seconds, because it talks to the receiving mail server. Going over 10 requests per second returns `429 Too Many Requests`. Throttle your client, back off when you get a 429 and honour the `Retry-After` header before retrying.

## FAQ

*   **What is the difference between `invalid`, `risky` and `unknown`?**

    `invalid` means the address cannot receive mail (for example the domain has no MX records). `risky` means the address may work but something about it is doubtful. `unknown` means the mail server would not confirm the mailbox, which is common for catch-all domains such as Google Workspace; the `reason` field says which case it is.

*   **What does `catch_all` mean?**

    The domain accepts mail for any address, so the SMTP check cannot tell whether this mailbox exists. Such addresses come back as `unknown` with reason `catch_all` and a middle score.

*   **Should I use `deep: true`?**

    Use it when you want the mailbox check over SMTP. Set it to `false` for faster checks that only look at syntax, MX, disposable and role addresses.

*   **Is `/v1/bulk` on the Free plan?**

    No. The Free plan has `/v1/health` and `/v1/validate`. Bulk validation is on Pro, Ultra and pay-as-you-go.

*   **Are the addresses stored?**

    No. Addresses are checked in memory and discarded.

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


Validate email addresses in one call: syntax, MX records, disposable and role addresses, typo suggestions and a live SMTP mailbox check.

MailForge Email Validator API: SMTP, MX, Disposable Check

PAYG