> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Validation API

> Validate one address or upload a list, start validation, inspect progress, and download results.

Email validation classifies addresses before sending. In the dashboard, open **Addons → Email validator**. Validation credits are separate from sending credits.

## Authentication

**Base URL:** `https://pro.api.serversmtp.com/api/v2`

Send `consumerKey` and `consumerSecret` headers with **Statistics & Management APIs** (`APIS`) permission. Its IP restrictions must allow your server. See [authentication](/docs/api-reference/authentication.md).

## Check the validation balance

`GET /emailvalidation/subscription` returns:

| Field | Meaning |
| - | - |
| `currency` | Currency for the paid balance. |
| `free_credits`, `free_credits_used`, `remaining_free_credit` | Allocated, used, and remaining validation units. One free credit validates one address. |
| `paid_credits` | Remaining monetary balance, not a count of addresses. Cost per validation varies with volume. |
| `latest_period_start_date`, `period_expiration_date` | Current free-credit period dates; may be `null`. |
| `last_used_period` | Last usage date; may be `null`. |

```bash Terminal theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/emailvalidation/subscription' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

## Validate one address

`POST /emailvalidation/validateEmail` accepts an `email` field:

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/emailvalidation/validateEmail' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"email":"recipient@example.net"}'
```

The response includes `email`, `status`, `sub_status`, `free_email`, `domain`, `domain_age_days`, `smtp_provider`, `mx_found`, and `mx_record`. Additional fields can include `did_you_mean`, `account`, `firstname`, `lastname`, `gender`, `country`, `region`, `city`, `zipcode`, and `processed_at`. Some enrichment fields can be `null`.

### Classification values

API status strings are lowercase:

| Status | Meaning |
| - | - |
| `valid` | Classified as valid. Delivery still depends on the receiving system. |
| `invalid` | Invalid address; remove it from your sending list. |
| `catch_all` | Domain accepts all addresses; mailbox validity is uncertain. |
| `spamtrap` | Suspected spam trap; exclude it from sending. |
| `abuse` | Known complaint risk; exclude it from sending. |
| `do_not_mail` | A category to review before sending; inspect `sub_status`. |
| `unknown` | Validation could not determine the outcome. |

`sub_status` gives detail such as `mailbox_not_found`, `no_dns_entries`, `failed_syntax_check`, `greylisted`, `role_based`, or `disposable`. It can be an empty string. Validation does not establish consent to receive email.

## Validate a list

### 1. Upload the file

`POST /emailvalidation/upload` accepts a multipart `file` field containing a CSV or TXT file with one address per line. Let curl set the multipart content type and boundary.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/emailvalidation/upload' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -F 'file=@/path/to/email-list.csv'
```

The `201` response contains a numeric `list_id` and `total_emails`:

```json theme={"system"}
{"list_id":10093,"total_emails":314}
```

Uploading creates the list. It does not start validation.

### 2. Start validation

Call `POST /emailvalidation/lists/{Id}/validate` with the returned `list_id`. No request body is required.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/emailvalidation/lists/10093/validate' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

The API reports `list_already_validated` or `insufficient_credit` with `400` when validation cannot start.

### 3. Read progress and results

`GET /emailvalidation/lists/{Id}` returns the list summary. Use `is_processed`, `percentage`, `total_emails`, and `total_processed` to check progress. Other fields are `id`, `creation_time`, `file_name`, and `status_summary` (an array of `{status, total}` objects).

```bash Terminal theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/emailvalidation/lists/10093' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET'
```

`GET /emailvalidation/lists/{Id}/emails` accepts optional positive `page` and `limit` parameters, defaulting to `1` and `10`. It returns `count`, `processed`, and `results`. Each result includes `email`, numeric `id`, and validation details such as `status`, `sub_status`, and MX information. Before validation, `processed` can be `0` and `results` empty.

For a full record, call `GET /emailvalidation/lists/{Id}/emails/{emailId}` using the result's `id`. The detail schema includes `account_id`, `list_id`, `id`, `email`, `created_at`, `did_you_mean`, and the shared validation fields.

### 4. Download the CSV

```bash Terminal theme={"system"}
curl 'https://pro.api.serversmtp.com/api/v2/emailvalidation/lists/10093/csv' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --output validation-results.csv
```

## List and delete uploaded lists

`GET /emailvalidation/lists` requires `from` and `to` dates in `YYYY-MM-DD` format. It accepts optional positive integer `page` and `limit`, plus `tz`, and returns `{count, results}` containing the list summaries described above.

Invalid parameters return `400` with `missing_required_parameter_from`, `missing_required_parameter_to`, `from_format_should_be_yyyy-mm-dd`, `to_format_should_be_yyyy-mm-dd`, `page_should_be_integer`, `page_should_be_greater_than_0`, `limit_should_be_integer`, or `limit_should_be_greater_than_0`.

```bash Terminal theme={"system"}
curl --get 'https://pro.api.serversmtp.com/api/v2/emailvalidation/lists' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  --data-urlencode 'from=2026-10-01' \
  --data-urlencode 'to=2026-10-27' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10'
```

`DELETE /emailvalidation/lists/{Id}` deletes an uploaded list and returns `{"success":true}`. An unknown list returns `404` with `message: "list_not_found"`.

## Buy additional validation credit

`POST /billing/buy_emailvalidation_credits` accepts integer `amount` from `15` to `1800`. This is a monetary purchase amount, not a validation count. An active plan is required.

```bash Terminal theme={"system"}
curl -X POST 'https://pro.api.serversmtp.com/api/v2/billing/buy_emailvalidation_credits' \
  -H 'consumerKey: YOUR_CONSUMER_KEY' \
  -H 'consumerSecret: YOUR_CONSUMER_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"amount":15}'
```

The response contains `url`, the billing link where you complete payment. Check the [current pricing](https://serversmtp.com/pricing/) and your subscription balance before purchasing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.