MailVeri REST API Reference

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.

Authentication

Authenticate all API requests by providing your API key in the Auth-Token HTTP header.

Auth-Token: mv_3f9a12bc4e89712a...

Rate Limits & Throttling

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

• /v1/get-balance/: 1 request per second.
• /v1/verify-mail/: 1 request per second per account.
• /v1/verify-mails/: Max 10 concurrent active batch jobs.

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.

curl -H "Auth-Token: YOUR_API_KEY" \
     https://api.mailveri.com/v1/get-balance/

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

2. Verify Single Email

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

curl -H "Auth-Token: YOUR_API_KEY" \
     -F "[email protected]" \
     https://api.mailveri.com/v1/verify-mail/

{
  "error": 0,
  "message": "Verify [email protected] successfully",
  "status": "VALID",
  "mail": "[email protected]",
  "balance": 4999
}

3. Upload File for Bulk Verification

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

curl -H "Auth-Token: YOUR_API_KEY" \
     -F "[email protected]" \
     https://api.mailveri.com/v1/verify-mails/

{
  "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.

curl -H "Auth-Token: YOUR_API_KEY" \
     "https://api.mailveri.com/v1/get-status/?id=sample_batch_id_9x8y7z"

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

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

5. Download Verification Results

Download a compressed ZIP archive containing categorized result lists.

# Download using cURL
curl -H "Auth-Token: YOUR_API_KEY" \
     --remote-header-name --remote-name \
     "https://api.mailveri.com/v1/download-result/?id=sample_batch_id_9x8y7z"

# Or download using wget
wget --header "Auth-Token: YOUR_API_KEY" \
     --content-disposition \
     "https://api.mailveri.com/v1/download-result/?id=sample_batch_id_9x8y7z"

6. Delete Batch Job

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

curl -X DELETE -H "Auth-Token: YOUR_API_KEY" \
     "https://api.mailveri.com/v1/delete-list/?id=sample_batch_id_9x8y7z"

{
  "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.

{
  "mcpServers": {
    "mailveri": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/mailveri/mailveri-mcp",
        "mailveri-mcp"
      ],
      "env": {
        "MAILVERI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Webhooks & HMAC SHA-256 Signing

Configure an HTTPS endpoint in your Webhooks Dashboard to receive instant notifications as soon as bulk verifications complete.

Event Payload Example

{
  "id": "sample_batch_id_9x8y7z",
  "status": "DONE",
  "download_link": "https://api.mailveri.com/v1/download-result/?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>.

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.