Email Validator API Documentation

Email Validator API Documentation

The Email Validator API provides comprehensive email address validation with multiple checks including format validation, domain verification, MX record verification, SMTP verification, and various security checks.

Note: If you don’t need programmatic access, you can use our web-based email validation tool.

Features

  • Email format validation (RFC 5322 compliant)
  • Domain existence and MX record verification
  • SMTP server validation (optional)
  • Disposable email detection
  • Role account detection
  • Honeypot detection
  • Free email provider detection
  • Provider reliability analysis
  • Comprehensive deliverability scoring
  • Detailed validation results
  • Webhook support for asynchronous processing
  • GDPR compliant
  • API versioning (v1 and v2)

Authentication

All API endpoints require an API key to be included in the request headers:

X-API-Key: your_api_key

Quick Start

Here’s a quick example using curl to validate an email address:

# Basic validation without SMTP check
curl -X POST "https://api.ozdreamtools.de/validate_email" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key" \
     -d '{
       "email": "example@domain.com",
       "smtp_check": false
     }'

# Full validation with SMTP check and webhook
curl -X POST "https://api.ozdreamtools.de/validate_email" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key" \
     -d '{
       "email": "example@domain.com",
       "smtp_check": true,
       "webhook_url": "https://your-webhook.com/callback"
     }'

# Test endpoint to check configuration
curl -X GET "https://api.ozdreamtools.de/validate_email/test" \
     -H "X-API-Key: your_api_key"

# Check remaining credits
curl -X GET "https://api.ozdreamtools.de/credits" \
     -H "X-API-Key: your_api_key"

Endpoint

POST /validate_email

Validates an email address and returns detailed validation results.

Request

POST https://api.ozdreamtools.de/validate_email
Content-Type: application/json
X-API-Key: your_api_key

{
    "email": "example@domain.com",
    "smtp_check": true,
    "webhook_url": "https://your-webhook.com/callback"
}

Parameters

ParameterTypeRequiredDescription
emailstringYesThe email address to validate
smtp_checkboolean/stringNoWhether to perform SMTP validation (default: false)
webhook_urlstringNoURL for receiving async validation results

Response

{
    "status": "success",
    "results": {
        "input_email": "example@domain.com",
        "normalized_email": "example@domain.com",
        "is_valid_format": true,
        "format_validation": {
            "is_valid": true,
            "issues": [],
            "local_part_length": 7,
            "domain_length": 10,
            "total_length": 18
        },
        "domain_validation": {
            "exists": true,
            "has_mx_records": true,
            "is_disposable": false,
            "mx_records": ["mx1.domain.com", "mx2.domain.com"],
            "is_free_provider": false,
            "provider_info": null
        },
        "security_checks": {
            "is_role_account": false,
            "is_disposable": false,
            "honeypot_analysis": {
                "is_honeypot": false,
                "confidence_score": 0.0,
                "risk_level": "low"
            },
            "has_suspicious_patterns": false,
            "pattern_matches": [],
            "quality_score": 1.0
        },
        "smtp_status": {
            "can_connect_smtp": true,
            "has_inbox_full": false,
            "is_deliverable": true,
            "is_disabled": false,
            "is_greylisted": false,
            "smtp_check_succeeded": true
        },
        "deliverability_score": 0.95,
        "details": [
            "Email format is valid",
            "Domain exists and is valid",
            "Found 2 MX records",
            "Final deliverability score: 95% (0.95)"
        ],
        "job_id": "unique_job_id",
        "credits_remaining": 99,
        "validation_level": "advanced",
        "api_version": "2"
    }
}

Error Response

{
    "status": "error",
    "error": "Error message description",
    "error_code": "VALIDATION_ERROR",
    "message": "An error occurred during email validation"
}

Response Fields Explanation

Format Validation

  • is_valid_format: Whether the email follows RFC 5322 format
  • local_part_length: Length of the part before @ symbol
  • domain_length: Length of the domain part
  • total_length: Total email length

Domain Validation

  • exists: Whether the domain exists
  • has_mx_records: Whether the domain has MX records
  • is_disposable: Whether it’s a disposable email domain
  • mx_records: List of MX records for the domain
  • is_free_provider: Whether the domain belongs to a free email provider
  • provider_info: Information about the email provider if it’s a known free provider

Security Checks

  • is_role_account: Whether it’s a role account (e.g., admin@, support@)
  • is_disposable: Whether it’s from a disposable email service
  • honeypot_analysis: Analysis of potential honeypot characteristics
  • has_suspicious_patterns: Whether suspicious patterns were detected
  • quality_score: Overall quality score (0.0 to 1.0)

SMTP Status (when smtp_check is true)

  • can_connect_smtp: Whether SMTP connection was successful
  • has_inbox_full: Whether the mailbox is full
  • is_deliverable: Whether the email is deliverable
  • is_disabled: Whether the account is disabled
  • is_greylisted: Whether the server uses greylisting

Overall Results

  • deliverability_score: Final score indicating likelihood of delivery (0.0 to 1.0)
  • details: Human-readable list of validation results
  • credits_remaining: Number of validation credits remaining
  • validation_level: “basic” or “advanced” (v2 only)
  • api_version: API version used for the request (v2 only)

API Versions

The API supports two versions:

Version 1 (v1)

  • Basic email validation
  • No SMTP check option
  • Limited response fields

Version 2 (v2)

  • Advanced validation with optional SMTP check
  • Additional validation fields
  • Provider information
  • Webhook support

Rate Limiting and Credits

  • Each validation request costs 1 mail credit
  • Credits are deducted upon successful API calls
  • The API returns remaining credits in the response
  • Use the /credits endpoint to check your balance

Test Endpoint

GET /validate_email/test

Test the email validator configuration without consuming credits.

Response

{
    "status": "configured",
    "configuration": {
        "smtp_enabled": true,
        "smtp_timeout": 10,
        "has_disposable_list": true,
        "has_role_prefixes": true
    }
}

Best Practices

  • Always check the deliverability_score for overall email quality
  • Use smtp_check: true only when high accuracy is required
  • Consider emails with scores above 0.7 as high quality

Data Privacy & GDPR Compliance

Our email validation service is fully GDPR-compliant, with all servers and API infrastructure located exclusively in Germany and Austria. This ensures that your data:

  • Remains within the European Union at all times
  • Is processed in accordance with EU data protection laws
  • Benefits from strict EU privacy standards
  • Is subject to GDPR safeguards and user rights

Data Storage Policy

We maintain a strict no-storage policy:

  • Email addresses and validation results are never stored on our servers
  • All data is processed in memory and immediately discarded after the response is sent
  • Previous validation results cannot be recovered – users are responsible for storing their own results
  • Job IDs are temporary and cannot be used to retrieve historical data

We do not store validated email addresses or transfer data outside the EU/EEA region.

Scroll to Top