API Overview

The ValidMail API provides programmatic access to email verification services. This RESTful API uses JSON for requests and responses.

Base URL

All API requests should be made to the following base URL:

https://validmail.io/api/v1

Endpoints

The API provides the following endpoints:

Request Format

All requests must include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request bodies should be JSON:

{
  "email": "test@example.com"
}

Response Format

All responses are returned in JSON format with consistent structure:

{
  "email": "test@example.com",
  "status": "valid",
  "score": 95,
  "verdict": "Email verified with high confidence",
  "checks": { ... },
  "meta": {
    "responseTime": 1234
  }
}

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The email address format is invalid",
    "status": 400
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

API Versioning

The API version is included in the URL path. The current version is v1.

When we make breaking changes, we'll release a new version. The previous version will remain available for a deprecation period.