Documentation / API Reference

Validation API

2 min read

The Validation API lets you verify email addresses before sending to reduce bounces and protect your sender reputation.

Validate single email

Validate a single email address.

POST /v1/validate/single

Request body

Field Type Required Description
email string Yes Email address to validate

Example request

curl -X POST https://api.mailingapi.com/v1/validate/single \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Response

{
  "email": "user@example.com",
  "valid": true,
  "result": "deliverable",
  "checks": {
    "syntax": "valid",
    "dns": "valid",
    "mx": "valid",
    "disposable": false,
    "role": false,
    "catch_all": false,
    "smtp": "valid"
  },
  "suggestion": null
}

Result types

Result Description Action
deliverable Mailbox exists Safe to send
undeliverable Mailbox doesn’t exist Don’t send
risky May bounce Send with caution
unknown Couldn’t verify Manual review

Check fields

Field Description
syntax Email format valid
dns Domain has DNS records
mx Domain has MX records
disposable Temporary email service
role Generic address (info@, admin@)
catch_all Domain accepts any address
smtp Mailbox exists (SMTP check)

Validate with typo suggestion

When validation detects a possible typo:

{
  "email": "user@gmial.com",
  "valid": false,
  "result": "undeliverable",
  "suggestion": "user@gmail.com"
}

Batch validation

Validate multiple emails in one request. For lists with more than 50 emails, the request is processed asynchronously. You receive a job_id and can poll GET /v1/validate/job/{job_id} for results.

POST /v1/validate/batch

Request body

Field Type Required Description
emails array Yes List of emails (max 1,000)

Example request

curl -X POST https://api.mailingapi.com/v1/validate/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user1@example.com",
      "user2@example.com",
      "invalid@nonexistent.domain"
    ]
  }'

Response

{
  "results": [
    {
      "email": "user1@example.com",
      "valid": true,
      "result": "deliverable",
      "checks": {
        "syntax": "valid",
        "dns": "valid",
        "mx": "valid",
        "disposable": false,
        "role": false
      }
    },
    {
      "email": "user2@example.com",
      "valid": true,
      "result": "deliverable",
      "checks": {
        "syntax": "valid",
        "dns": "valid",
        "mx": "valid",
        "disposable": false,
        "role": false
      }
    },
    {
      "email": "invalid@nonexistent.domain",
      "valid": false,
      "result": "undeliverable",
      "checks": {
        "syntax": "valid",
        "dns": "invalid",
        "mx": "invalid",
        "disposable": false,
        "role": false
      }
    }
  ],
  "summary": {
    "total": 3,
    "deliverable": 2,
    "undeliverable": 1,
    "risky": 0,
    "unknown": 0
  }
}

Quick validation

Fast validation without network operations (no MX/SMTP checks).

POST /v1/validate/quick

Request body

Field Type Required Description
email string Yes Email address to validate

Checks performed

  • Syntax validation
  • Disposable domain detection
  • Role-based email detection
  • Suppression list check

Example request

curl -X POST https://api.mailingapi.com/v1/validate/quick \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Batch job status

Check the status of an asynchronous batch validation job.

GET /v1/validate/job/{job_id}

Example request

curl https://api.mailingapi.com/v1/validate/job/abc123xyz \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "job_id": "abc123xyz",
  "status": "completed",
  "total_emails": 500,
  "processed": 500,
  "results": [...],
  "created_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:02:30Z"
}

Job statuses

Status Description
pending Job created, not yet started
processing Validation in progress
completed All emails validated
failed Job failed

Error codes

Code Description
invalid_email_format Email syntax is invalid
job_not_found Job ID not found
file_too_large File exceeds 100 MB
too_many_emails Exceeds 1 million limit
invalid_file_format Unsupported file type
job_already_completed Cannot cancel completed job