API Documentation

Integrate email validation into your applications with our REST API.

POST

/api/validate

Validate a single email address

Request Body

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

Response

{
  "email": "test@example.com",
  "isValid": true,
  "score": 85,
  "deliverability": "deliverable",
  "risk": "low",
  "checks": {
    "syntax": {
      "valid": true,
      "message": "Email syntax is valid"
    },
    "domain": {
      "valid": true,
      "exists": true,
      "message": "Domain format is valid"
    },
    "mx": {
      "valid": true,
      "records": ["mx1.example.com", "mx2.example.com"],
      "message": "Found 2 MX record(s)"
    },
    "disposable": {
      "isDisposable": false,
      "message": "Not a disposable email domain"
    },
    "roleBased": {
      "isRoleBased": false,
      "role": null
    },
    "freeProvider": {
      "isFree": false,
      "provider": null
    },
    "typo": {
      "hasTypo": false,
      "suggestion": null
    },
    "blacklisted": {
      "isBlacklisted": false,
      "lists": []
    },
    "catchAll": {
      "isCatchAll": false
    }
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Example (cURL)

curl -X POST https://your-domain/api/validate \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
POST

/api/validate-bulk

Validate multiple email addresses (max 1000 per request)

Request Body

{
  "emails": [
    "test1@example.com",
    "test2@example.com",
    "test3@gmail.com"
  ]
}

Response

[
  {
    "email": "test1@example.com",
    "isValid": true,
    "score": 85,
    ...
  },
  {
    "email": "test2@example.com",
    "isValid": true,
    "score": 80,
    ...
  },
  {
    "email": "test3@gmail.com",
    "isValid": true,
    "score": 95,
    ...
  }
]

Example (cURL)

curl -X POST https://your-domain/api/validate-bulk \
  -H "Content-Type: application/json" \
  -d '{"emails": ["test1@example.com", "test2@gmail.com"]}'
GET

/api/health

Check API health status

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "endpoints": {
    "validate": "POST /api/validate",
    "validateBulk": "POST /api/validate-bulk",
    "health": "GET /api/health"
  }
}

Response Fields Explained

isValid

Boolean indicating if the email passes all critical checks

score

Quality score from 0-100 based on all validation checks

deliverability

deliverable | risky | undeliverable | unknown

risk

low | medium | high - risk level assessment

Rate Limits

Single Validation: 100 requests per minute

Bulk Validation: 10 requests per minute

Max Bulk Size: 1000 emails per request