# MailVeri REST API Reference | Email Verification API Docs

> MailVeri REST API Documentation - Verify email deliverability, check balances, perform bulk verifications, configure webhooks, and integrate MCP AI assistants.

- **Source**: https://mailveri.com/docs/api
- **AI Reference**: https://mailveri.com/llms-full.txt

---

The MailVeri API allows you to verify individual email deliverability, trigger high-speed distributed batch verification, track processing progress, download results, and subscribe to secure real-time webhooks.

Base Production URL: `https://api.mailveri.com/v1`

Authentication Header: `Authorization: Bearer <api_key>`

AI / Markdown: [View as Markdown (.md)](https://mailveri.com/docs/api.md)

## Overview

MailVeri inspects mailbox existence directly against recipient mail exchangers without sending actual emails. It performs RFC syntax checks, DNS MX resolution, disposable email filtering, spam trap analysis, catch-all detection, full mailbox identification, and SMTP handshake verification.

| Status Code | Description | Deliverability Advice |
| --- | --- | --- |
| VALID | Mailbox is verified and accepted by the destination SMTP server. | Safe to send. Lowest bounce probability. |
| INVALID | Mailbox does not exist, domain has no MX records, or address was explicitly rejected. | Do not send. Hard bounce guaranteed. |
| DISPOSABLE | Temporary, throwaway email service (e.g. GuerrillaMail, 10MinuteMail). | Block or filter out to preserve reputation. |
| ROLE_ACCOUNT | Generic role address (e.g. admin@, support@, info@, sales@). | Higher complaint risk; proceed with care. |
| CATCH_ALL | The domain accepts any email address regardless of whether the mailbox exists. | Proceed cautiously; deliverability cannot be guaranteed. |
| FULL_INBOX | Mailbox exists but its storage quota has been exceeded. | Soft bounce. May retry later. |
| UNKNOWN | Remote server timed out, greylisted the probe, or refused connection. | Free of charge. Credits are automatically refunded. |

## Authentication

Authenticate all API requests by providing your API key as a Bearer token in the `Authorization` HTTP header.

HTTP Header

```http
Authorization: Bearer mv_3f9a12bc4e89712a...
```

**Multi-Key Support & Lifecycle:**
You can create up to 5 concurrent active API keys in your [MailVeri Dashboard](https://app.mailveri.com/api-keys/). Each key can have an optional expiration date (7, 30, 60, 90 days, or never). Keys can be renamed or revoked at any time. Revoked or expired keys immediately return `403 Forbidden`.

## Rate Limits & Throttling

Rate limits are enforced **per account** (across all API keys) to protect cluster resources:

- `/v1/get-balance/`: Unthrottled (read-only balance check).
- `/v1/verify-mail/`: 10 requests per second per account (up to 5 concurrent in-flight checks).
- `/v1/verify-mails/`: 100 requests per second (max 10 concurrent active batch jobs, up to 1,000,000 emails per batch).

When rate limits are exceeded, the API responds with HTTP `429 Too Many Requests`. Please implement exponential backoff retry strategies.

## 1. Get Account Balance

Retrieve your account's remaining email verification credit balance.

GET /v1/get-balance/

Free • 0 Credits

cURL Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.mailveri.com/v1/get-balance/
```

JSON Response (HTTP 200)

```json
{
  "error": 0,
  "message": "You have 5000 credits",
  "balance": 5000
}
```

## 2. Verify Single Email

Verify delivery status for a single email address in real time.

POST /v1/verify-mail/

1 Credit (Refunded if UNKNOWN)

### Parameters (JSON, Form Data, or URL-encoded)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Required | The email address to verify (e.g. `alex@example.com`). Legacy alias `mail` is also accepted. |

cURL Example (JSON & Form Data Supported)

```bash
# Option 1: JSON payload (Recommended)
curl -X POST https://api.mailveri.com/v1/verify-mail/ \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"email": "alex@example.com"}'

# Option 2: Form / URL-encoded
curl -X POST https://api.mailveri.com/v1/verify-mail/ \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d "email=alex@example.com"
```

JSON Response (HTTP 200)

```json
{
  "error": 0,
  "message": "Verified alex@example.com successfully",
  "status": "VALID",
  "email": "alex@example.com",
  "mail": "alex@example.com",
  "balance": 4999,
  "credits_used": 1,
  "quality_score": 98,
  "is_forwarding": false
}
```

### Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Primary deliverability status (`VALID`, `INVALID`, `DISPOSABLE`, `ROLE_ACCOUNT`, `CATCH_ALL`, `FULL_INBOX`, `UNKNOWN`). |
| `credits_used` | integer | Credits deducted for this call: `1` on conclusive verdicts (`VALID`, `INVALID`, `DISPOSABLE`, `ROLE_ACCOUNT`, `CATCH_ALL`, `FULL_INBOX`); `0` on `UNKNOWN` verdicts and error responses. |
| `quality_score` | integer | Deliverability confidence score (`0`–`100`) based on mailbox existence, provider reputation, role status, and relay penalties. |
| `is_forwarding` | boolean | `true` if the recipient domain routes incoming mail via an email forwarding relay (e.g. Cloudflare Email Routing, SimpleLogin, AnonAddy, Apple Private Relay). |
| `balance` | integer | Remaining account verification credit balance. |

## 3. Upload File for Bulk Verification

Submit a file containing a list of emails for distributed verification across our worker cluster.

POST /v1/verify-mails/

1 Credit / Unique Email

### Parameters (Multipart Form-Data)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | Required | Text (`.txt`) or CSV (`.csv`) file with one email per line. Max size: 100MB. Minimum: 2 unique emails. |

cURL Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -F "file=@leads.txt" \
     https://api.mailveri.com/v1/verify-mails/
```

JSON Response (HTTP 200)

```json
{
  "error": 0,
  "message": "List leads.txt with 500 unique mails was uploaded and queued successfully",
  "id": "sample_batch_id_9x8y7z",
  "count": 500
}
```

## 4. Get Batch Job Status

Poll verification progress (percentage completed) and receive the final download link.

GET /v1/get-status/

Free • 0 Credits

### Query Parameters

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Required | The batch verification job ID returned from `/v1/verify-mails/`. |

cURL Example

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.mailveri.com/v1/get-status/?id=sample_batch_id_9x8y7z"
```

In-Progress Response

```json
{
  "error": 0,
  "status": "PROCESSING",
  "percent": 65,
  "download_link": ""
}
```

Completed Response

```json
{
  "error": 0,
  "status": "DONE",
  "percent": 100,
  "download_link": "https://api.mailveri.com/v1/download-zip/?id=sample_batch_id_9x8y7z"
}
```

## 5. Download Verification Results

Download a compressed ZIP archive containing categorized result lists (via `/v1/download-zip/`) or a custom filtered CSV (via `/v1/download-result/`).

GET /v1/download-zip/ /v1/download-result/

Free • 0 Credits

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Required | The batch ID returned from `/v1/verify-mails/`. |
| `format` | string | Optional | Set to `csv` to stream a filtered CSV file. Defaults to full ZIP archive. |
| `status` | string | Optional | Comma-separated deliverability statuses (e.g. `VALID,ROLE_ACCOUNT`, `VALID`, `INVALID`). Default for CSV: `VALID,ROLE_ACCOUNT`. |
| `columns` | string | Optional | CSV column layout: `original` (preserves original columns with status column appended), `compact` (Email, Status), or `email` (Email only). Default: `original`. |

Download Examples (cURL)

```bash
# 1. Download full result archive (ZIP - recommended):
curl -H "Authorization: Bearer YOUR_API_KEY" \
     --remote-header-name --remote-name \
     "https://api.mailveri.com/v1/download-zip/?id=sample_batch_id_9x8y7z"

# 2. Download custom filtered CSV (e.g. deliverable emails with original columns):
curl -H "Authorization: Bearer YOUR_API_KEY" \
     --remote-header-name --remote-name \
     "https://api.mailveri.com/v1/download-result/?id=sample_batch_id_9x8y7z&format=csv&status=VALID,ROLE_ACCOUNT&columns=original"

# 3. Download clean list of valid emails only (single column):
curl -H "Authorization: Bearer YOUR_API_KEY" \
     --remote-header-name --remote-name \
     "https://api.mailveri.com/v1/download-result/?id=sample_batch_id_9x8y7z&format=csv&status=VALID&columns=email"
```

## 6. Delete Batch Job

Cancel an active verification or delete a completed list from storage.

DELETE /v1/delete-list/

Free • 0 Credits

cURL Example

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.mailveri.com/v1/delete-list/?id=sample_batch_id_9x8y7z"
```

JSON Response (HTTP 200)

```json
{
  "error": 0,
  "message": "List leads.txt was deleted successfully",
  "id": "sample_batch_id_9x8y7z"
}
```

## Model Context Protocol (MCP) Server

Integrate MailVeri directly into AI tools (Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Antigravity, OpenCode, Pi, Oh My Pi, VS Code) using the open-source MCP protocol.

Looking for client setup guides (Claude Desktop, Claude Code, Codex, Cursor, Windsurf, Antigravity, OpenCode, Pi, Oh My Pi, VS Code/Cline) and detailed tool input/output JSON schemas? View the dedicated [MailVeri MCP v2 Documentation →](https://mailveri.com/docs/mcp)

Hosted Streamable HTTP Config (.cursor/mcp.json / .mcp.json)

```json
{
  "mcpServers": {
    "mailveri": {
      "url": "https://mcp.mailveri.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

| MCP Tool Name | Description |
| --- | --- |
| `mailveri_verify_email` | Verify deliverability of a single email address. |
| `mailveri_get_balance` | Fetch current account verification credits. |
| `mailveri_verify_batch` | Submit a list of emails for bulk verification. |
| `mailveri_get_batch_status` | Check batch completion percentage and download link. |
| `mailveri_download_batch_result` | Get secure URL to download batch results (full ZIP archive or custom filtered CSV by `status` and `columns`). |
| `mailveri_delete_batch` | Delete a finished or canceled batch job (active queued or processing jobs cannot be deleted). |

## Webhooks & HMAC SHA-256 Signing

Configure an HTTPS endpoint in your [Webhooks Dashboard](https://app.mailveri.com/webhooks/) to receive instant notifications as soon as bulk verifications complete. Outbound requests carry the official User-Agent: `MailVeri/2.0 (+https://mailveri.com)`.

### Event Payload Example

POST Request sent to your Webhook URL

```json
{
  "id": "sample_batch_id_9x8y7z",
  "status": "DONE",
  "download_link": "https://api.mailveri.com/v1/download-zip/?id=sample_batch_id_9x8y7z"
}
```

### Verifying Signatures

When webhook signing is enabled, requests include the `X-Webhook-Signature` header formatted as `t=<timestamp>,v1=<signature>`.

Python HMAC Verification

```python
import hmac
import hashlib
import json

def verify_mailveri_webhook(payload_body, sig_header: str, secret: str) -> bool:
    pairs = dict(item.split('=', 1) for item in sig_header.split(','))
    timestamp = pairs.get('t', '')
    expected_sig = pairs.get('v1', '')

    # Re-serialize to compact JSON (matches signing format)
    data = json.loads(payload_body) if isinstance(payload_body, (str, bytes)) else payload_body
    compact = json.dumps(data, separators=(',', ':'), sort_keys=True)
    signed_payload = f"{timestamp}.{compact}"
    computed_sig = hmac.new(secret.encode('utf-8'), signed_payload.encode('utf-8'), hashlib.sha256).hexdigest()

    return hmac.compare_digest(computed_sig, expected_sig)
```

## Error Codes Reference

Summary of API response error codes and HTTP status codes.

| HTTP Status | API Error Code | Message / Cause | Solution |
| --- | --- | --- | --- |
| `403 Forbidden` | - | API key is missing, invalid, revoked, or expired. | Generate or select an active key under [API Keys](https://app.mailveri.com/api-keys/). |
| `429 Too Many Requests` | - | Exceeded rate limits (10 req/sec or 5 concurrent checks on `/v1/verify-mail/`). | Throttle requests and implement exponential backoff. |
| `200 OK` | `error: 1` | Missing required parameter (e.g. `mail`, `file`, `id`). | Supply all mandatory request parameters. |
| `200 OK` | `error: 2` | Insufficient credits or batch list not found. | Check balance or verify the batch UUID provided. |
| `200 OK` | `error: 3` | Wrong email syntax or empty uploaded file. | Ensure the email or file complies with standard formatting. |
| `200 OK` | `error: 4` | Fewer than 2 unique emails in batch upload. | Minimum batch size is 2 emails. For single emails, use `/v1/verify-mail/`. |
| `200 OK` | `error: 7` | Maximum 10 concurrent active lists reached. | Wait for running jobs to finish before submitting new lists. |

© 2026 MailVeri. All rights reserved. [Website](https://mailveri.com/) • [Docs Hub](https://mailveri.com/docs) • [Pricing ($59/100K)](https://mailveri.com/pricing) • [Compare 36 Verifiers](https://mailveri.com/compare) • [Integrations](https://mailveri.com/integrations) • [Wholesale API](https://mailveri.com/wholesale-api) • [Dashboard](https://app.mailveri.com) • [REST API Reference](https://mailveri.com/docs/api) • [MCP for AI](https://mailveri.com/docs/mcp) • [API Keys](https://app.mailveri.com/api-keys/) • [Webhooks](https://app.mailveri.com/webhooks/) • [GitHub MCP](https://github.com/mailveri/mailveri-mcp)

## Frequently Asked Questions

### How do I verify a single email address via the MailVeri REST API?

Send a POST request to https://api.mailveri.com/v1/verify-mail/ with header Authorization: Bearer YOUR_API_KEY and JSON payload {"email": "user@example.com"}. The response returns status, email, and remaining balance.

### How do MailVeri batch verification webhooks work?

When a bulk list uploaded via POST https://api.mailveri.com/v1/verify-mails/ finishes processing, MailVeri dispatches an automated POST webhook with User-Agent: MailVeri/2.0 (+https://mailveri.com) and an HMAC-SHA256 X-Webhook-Signature header.