# 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://eev.stoplight.io/docs/eev/92f233b1d47b3-java-script-widget), or the application's backend |
| Connect to an existing platform | Check the [integrations](https://www.easyemailverification.com/en-US/integrations) first |

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.

## 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.
- Avoid logging full email addresses; apply the application's privacy and retention rules to results.

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

## 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
- Official documentation: https://eev.stoplight.io/docs/eev/122963476e10f-getting-started
- Integrations: https://www.easyemailverification.com/en-US/integrations