API Documentation

VeriMail Endpoints

Real-time email validation for clean data

Base URL & Authentication

All API requests must be made over HTTPS to the production environment. Plaintext HTTP requests will fail.

Base URL: https://api.verimail.io/v2

Authenticate using your project API key via the Authorization header. Keys can be generated in your VeriMail dashboard under Settings > API Access.

Example Header

Authorization: Bearer vm_live_sk_8f9a2c1d4e5b6f7g8h9i0j1k2l3m4n5o

Available Endpoints

VeriMail exposes three core endpoints for single checks, bulk processing, and job monitoring.

POST /verify

Validates a single email address in real-time. Returns syntax, MX, SMTP, and disposable/role-based flags.

POST /batch

Submits up to 10,000 emails for asynchronous processing. Returns a job ID for tracking.

GET /status

Retrieves the progress and results of a batch job using the provided job ID.

Request Parameters

Configure validation depth and output format using query or body parameters.

/verify Parameters

email (string, required): The address to validate.

smtp_verify (boolean, optional): Enable live SMTP handshake. Default: true.

format (string, optional): Response format. Values: json, csv. Default: json.

{
  "email": "sarah.connor@techops.com",
  "smtp_verify": true,
  "format": "json"
}

/batch Parameters

emails (array, required): List of email strings. Max 10,000 per request.

webhook_url (string, optional): HTTPS endpoint for completion callbacks.

{
  "emails": ["admin@startup.io", "billing@corp.net"],
  "webhook_url": "https://hooks.yourapp.com/verimail-batch"
}

Response Formats & Codes

All successful responses return HTTP 200. Rate limits trigger 429, and malformed requests return 400 with detailed error messages.

/verify Success Response

{
  "status": "valid",
  "email": "sarah.connor@techops.com",
  "mx_found": true,
  "smtp_valid": true,
  "disposable": false,
  "role_based": false,
  "risk_score": 0.05,
  "processed_at": "2024-06-15T14:32:01Z"
}

/batch & /status Response

{
  "job_id": "jb_9f8e7d6c5b4a3210",
  "status": "completed",
  "total_records": 2,
  "results_url": "https://api.verimail.io/v2/jobs/jb_9f8e7d6c5b4a3210/download",
  "expires_at": "2024-06-22T14:32:01Z"
}

Error responses follow the RFC 7807 Problem Details standard. Include a retry_after header when hitting the 150 requests/minute quota.