# Easy Email Verification — setup guide for AI agents

Easy Email Verification (EEV) verifies email addresses through a REST API: syntax, domain and MX checks, mailbox acceptance, and risk signals such as disposable, role-based and catch-all addresses. No email is sent to the recipient.

This guide is for AI coding assistants and agents that integrate EEV into an application. Exact parameters, fields and status codes are in the [API reference](https://www.easyemailverification.com/docs/api-reference.md), generated from the [OpenAPI specification](https://www.easyemailverification.com/openapi.json). Do not invent EEV behavior that is not documented there.

## 1. Get an API key

If the user has no API key, send them to create an account and a key:

- Create an account: https://dashboard.easyemailverification.com/register?utm_source=agents_md
- Create or manage API keys: https://dashboard.easyemailverification.com/apisettings

Never ask the user to paste the key into the conversation, source code or documentation. Ask them to store it in an environment variable such as `EEV_API_KEY`, or in the application's secrets manager.

## 2. Test without an account (sandbox)

The public key `eev_sandbox_key` returns fixed answers for addresses at `sandbox.easyemailverification.com`. It needs no account and consumes no credits, so use it to check an integration before using a real key.

```bash
curl --get "https://api.easyemailverification.com/v1/verify" \
  -H "X-API-Key: eev_sandbox_key" \
  --data-urlencode "email=unknown@sandbox.easyemailverification.com"
```

Useful sandbox addresses: `valid@`, `invalid@`, `unknown@`, `disposable@`, `catchall@`, `role@`, `quota@` (returns 402) and `ratelimit@` (returns 429), all at `sandbox.easyemailverification.com`, plus `typo@gmial.com` (returns a `did_you_mean` suggestion). Sandbox answers carry the header `X-EEV-Sandbox: true`. The sandbox key works on `GET /verify`, `POST /verify` and `GET /credits`, not on the bulk endpoints.

## 3. Choose the integration

| Need | Use |
| --- | --- |
| Verify one address (signup, form submit, import of one record) | `GET /v1/verify` from the application's backend |
| Verify up to 50 addresses at once | `POST /v1/verify` |
| Verify a list (hundreds or more) | Bulk endpoints: `POST /v1/bulk/upload`, then status and download |
| Validate a web form in the browser | The official [JavaScript widget](https://www.easyemailverification.com/widget.md), or the application's backend |
| Connect to an existing platform | Check the [integrations](https://www.easyemailverification.com/en-US/integrations) first |
| Let an AI assistant verify addresses itself (Claude Code, Cursor, Gemini CLI...) | The hosted MCP server: see section 12 |

Do not loop over `GET /v1/verify` to verify large lists. Use the bulk endpoints.

## 4. Verify one address

Send the key in the `X-API-Key` header (recommended). The `apikey` query parameter and the `Authorization` header also work; see the API reference.

```bash
curl --get "https://api.easyemailverification.com/v1/verify" \
  -H "X-API-Key: $EEV_API_KEY" \
  --data-urlencode "email=john@example.com"
```

Node.js 18+:

```javascript
async function verifyEmail(email) {
  const apiKey = process.env.EEV_API_KEY;
  if (!apiKey) throw new Error("EEV_API_KEY is not configured");

  const url = new URL("https://api.easyemailverification.com/v1/verify");
  url.searchParams.set("email", email);

  const response = await fetch(url, {
    headers: { "X-API-Key": apiKey, Accept: "application/json" },
    signal: AbortSignal.timeout(30000),
  });
  const data = await response.json();
  if (!response.ok || data.success === false) {
    throw new Error(`EEV error ${response.status}: ${data.message ?? "unknown error"}`);
  }
  return data; // use data.result, data.reason, data.safe_to_send
}
```

Python 3:

```python
import os
import requests

def verify_email(email: str) -> dict:
    response = requests.get(
        "https://api.easyemailverification.com/v1/verify",
        params={"email": email},
        headers={"X-API-Key": os.environ["EEV_API_KEY"]},
        timeout=30,
    )
    data = response.json()
    if response.status_code != 200 or not data.get("success"):
        raise RuntimeError(f"EEV error {response.status_code}: {data.get('message')}")
    return data
```

PHP:

```php
function verifyEmail(string $email): array {
    $ch = curl_init('https://api.easyemailverification.com/v1/verify?email=' . urlencode($email));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('EEV_API_KEY')],
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode((string) $body, true);
    if ($status !== 200 || empty($data['success'])) {
        throw new RuntimeException('EEV error ' . $status . ': ' . ($data['message'] ?? 'unknown error'));
    }
    return $data;
}
```

A verification can take several seconds because it talks to the recipient's mail server. Use a timeout of about 30 seconds and do not block a form indefinitely.

## 5. Verify a small batch

Up to 50 addresses per request. The answer is a list with one result per address.

```bash
curl -X POST "https://api.easyemailverification.com/v1/verify" \
  -H "X-API-Key: $EEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["john@example.com", "mary@example.com"]}'
```

## 6. Verify a list (bulk)

The bulk workflow is asynchronous:

1. Upload a TXT or CSV file with one address per line (maximum 16 MB). The account needs enough credits for every address.

   ```bash
   curl -X POST "https://api.easyemailverification.com/v1/bulk/upload" \
     -H "X-API-Key: $EEV_API_KEY" \
     -F "file=@leads.csv"
   ```

   The answer contains `list_id`.

2. Poll the job until `status` is `completed` (every few seconds; large lists take longer). Other final states are `failed` and `not_enough_credits`.

   ```bash
   curl "https://api.easyemailverification.com/v1/bulk/status/LIST_ID" -H "X-API-Key: $EEV_API_KEY"
   ```

3. Download the results as CSV.

   ```bash
   curl "https://api.easyemailverification.com/v1/bulk/download/LIST_ID" -H "X-API-Key: $EEV_API_KEY" -o results.csv
   ```

4. Optionally delete the job: `DELETE /v1/bulk/LIST_ID`. Jobs and results are deleted automatically 30 days after upload.

`GET /v1/bulk/status` lists the account's jobs.

## 7. Check the remaining credits

```bash
curl "https://api.easyemailverification.com/v1/credits" -H "X-API-Key: $EEV_API_KEY"
```

This call does not consume credits.

## 8. Interpret the result

- `result` is `valid`, `invalid` or `unknown`. `reason` gives the detail (for example `accepted_email`, `rejected_email`, `invalid_domain`, `no_mx_record`, `timeout`).
- `unknown` means EEV could not reach a reliable conclusion. Do not map it to `valid` or to `invalid`; decide according to the application's risk policy. A later attempt may give a definitive result.
- `safe_to_send` is EEV's overall recommendation for sending.
- `disposable`, `role`, `free` and `accept_all` are signals, not decisions. Whether to accept them is the application's choice.
- `did_you_mean` suggests a correction when a typo is detected; show it to the user instead of rejecting silently.
- `success: true` only means the request was processed. It does not mean the address is valid.

## 9. Errors and retries

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | Missing API key or parameter | Fix the request |
| 401 | Unknown key, or a widget-only key used on the API | Check the key |
| 402 | No credits left | Tell the user; do not retry |
| 429 | Too many addresses in one batch (POST, max 50), or sandbox limit | Reduce the batch or slow down |
| 5xx / timeout | Temporary failure | Retry later with backoff, at most a few times |

Each verification may consume a credit even if the response is lost on the way back, so do not retry verifications in a tight loop.

Rate limits: the REST API has no per-minute limit for accounts. The limits are 50 addresses per `POST /verify` request (more returns 429), the credit balance, and 60 requests per minute for the sandbox key. Send one request at a time per address and use the bulk endpoints for lists.

## 10. Security

- Keep the API key on a trusted server, in an environment variable or a secrets manager.
- Never put the key in browser JavaScript, mobile apps, public repositories, documentation or logs.
- Prefer the `X-API-Key` header: query strings end up in access logs, proxies and monitoring tools. Send only one key mechanism per request: if both are present, the `apikey` query parameter wins.
- Avoid logging full email addresses; apply the application's privacy and retention rules to results.

## Pricing and credits

Current prices are at https://www.easyemailverification.com/en-US/pricing; quote that page rather than these numbers if they differ.

- Free plan: 50 verifications per day with a free account, no credit card.
- Pay-as-you-go: prepaid credits from US$ 4 for 500 verifications; prepaid credits never expire. Monthly subscriptions are also available.
- Each verified address uses one credit. Results with `reason: no_connect` (the receiving server could not be reached) are free, and so is `GET /credits`.
- A bulk job needs credits for every address in the file before it starts.

## Data handling

- Addresses verified one at a time, in the email checker or through the API, are not retained.
- Bulk verification result files are kept for 30 days so they can be downloaded, and are then deleted.
- Account data (name, email and credentials) is stored to provide the service.
- Details: https://www.easyemailverification.com/en-US/privacy-policy and https://www.easyemailverification.com/en-US/data-protection

## 11. Rules for AI coding assistants

1. Use only the endpoints, parameters and fields documented in the API reference or the OpenAPI specification.
2. Do not invent endpoints, parameters, enum values, limits, quotas or pricing.
3. Read the key from `EEV_API_KEY` or a secrets manager; never hard-code it and never ask the user to paste it.
4. Call EEV from the backend; never expose the key in client code.
5. Test with `eev_sandbox_key` before using a real key.
6. Use the bulk endpoints for lists, not a loop over `GET /verify`.
7. Treat `unknown` as neither valid nor invalid, and `success: true` as no proof of validity.
8. Handle timeouts, network errors, HTTP errors and API errors.
9. Leave policy decisions (block disposable, role or free addresses) to the user unless they asked for them.

## 12. Connect an MCP client

For an assistant that should verify addresses as a tool, instead of code that calls the API, use the hosted MCP server (beta):

- URL: `https://mcp.easyemailverification.com/mcp` (Streamable HTTP, stateless, POST only)
- Authentication: OAuth (clients that support it, such as claude.ai, only need the URL; the user signs in and allows the app) or the user's API key in the `X-API-Key` header.
- Tools: `verify_email` (one address), `verify_emails` (1 to 50), `get_credits` (free), and for lists up to 10,000 `create_bulk_job`, `get_bulk_status`, `get_bulk_summary` (totals and at most 50 example rows) and `delete_bulk_job`. Each verified address uses one credit; errors (invalid key, no credits, rate limit) come back as tool errors. Bulk tools do not accept the sandbox key.

Claude Code signs in with OAuth: run the command below, then type `/mcp` in a Claude Code session, select `eev` and choose Authenticate.

```bash
claude mcp add --transport http --scope user eev https://mcp.easyemailverification.com/mcp
```

Claude Code with an API key instead (for scripts or non-interactive use):

```bash
claude mcp add --transport http --scope user eev https://mcp.easyemailverification.com/mcp --header "X-API-Key: YOUR_API_KEY"
```

Clients with a JSON configuration (the URL field is `url` in Cursor, `serverUrl` in Windsurf and `httpUrl` in Gemini CLI):

```json
{
  "mcpServers": {
    "eev": {
      "url": "https://mcp.easyemailverification.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

The user writes the key into the command or the configuration file themselves; do not ask for it in the conversation. Setup for each client: https://www.easyemailverification.com/en-US/mcp. Step-by-step guides an assistant can follow: https://www.easyemailverification.com/claude.md and https://www.easyemailverification.com/gemini.md.

## Sources

- API reference: https://www.easyemailverification.com/docs/api-reference.md
- OpenAPI specification: https://www.easyemailverification.com/openapi.json
- Everything in one file: https://www.easyemailverification.com/llms-full.txt
- API documentation: https://www.easyemailverification.com/en-US/api
- Integrations: https://www.easyemailverification.com/en-US/integrations