API Documentation - EmailsValid.com

📑 Table of Contents

Overview
Features
Single Email Validation
Bulk CSV Validation
Get Emails from Database
Get Statistics
Export Valid Emails
Demographic Categories
Error Handling

🚀 Overview

EmailsValid.com provides a comprehensive email validation and demographic enrichment API. Validate email addresses, verify domains, and automatically categorize contacts with AI-powered demographic analysis.

Base URL: https://emailsvalid.com
Content-Type: application/json for POST requests

✨ Features

✉️ Email Validation

Two-stage validation with syntax checking and DNS/MX record verification.

🎯 AI Demographic Enrichment

Automatically categorize emails by profession, industry, and company using AI.

📤 Bulk Processing

Upload CSV files with thousands of emails for batch validation.

💾 Database Storage

All validated emails are stored for easy access and export.

📊 Analytics Dashboard

View statistics and demographic breakdowns of your email database.

📥 CSV Export

Export valid emails with demographic data to CSV files.

✉️ Single Email Validation

POST /validate

Validate a single email address with full demographic enrichment.

Request Body

Parameter	Type	Required	Description
`email`	string	Required	Email address to validate

Example Request

curl -X POST https://emailsvalid.com/validate \
  -H "Content-Type: application/json" \
  -d '{"email": "john.doe@company.com"}'
        

✅ Success Response

{
  "email": "john.doe@company.com",
  "valid": true,
  "validation_status": "valid",
  "demographic_category": "business_professional",
  "demographic_subcategory": "sales",
  "confidence_score": 0.87,
  "domain_info": {
    "domain": "company.com",
    "mx_records": ["mx1.company.com", "mx2.company.com"],
    "has_mx": true
  }
}
            

❌ Invalid Email Response

{
  "email": "invalid..email@test",
  "valid": false,
  "validation_status": "format_error",
  "error_category": "format",
  "error_details": "Consecutive dots not allowed"
}
            

📤 Bulk CSV Validation

Upload CSV File

POST /upload

Upload a CSV file containing emails for batch validation. Returns a job ID for tracking progress.

Request

Parameter	Type	Required	Description
`file`	file	Required	CSV file with 'Email' column
`enrich`	boolean	Optional	Enable AI demographic enrichment (default: true)

📋 CSV Format: Your file must have an Email column header. Download template

✅ Success Response

{
  "job_id": "abc123-def456-ghi789",
  "message": "Processing started",
  "total_emails": 1500
}
            

Check Job Status

GET /status/{job_id}

Check the processing status of a bulk validation job.

✅ Success Response

{
  "job_id": "abc123-def456-ghi789",
  "total": 1500,
  "processed": 450,
  "status": "processing",
  "valid_count": 380,
  "format_errors_count": 25,
  "verification_errors_count": 45
}
            

Download Results

GET /download/{job_id}/{file_type}

Download result CSV files after validation completes.

file_type	Description
`valid`	Valid emails with demographic data
`format_errors`	Emails with format/syntax errors
`verification_errors`	Emails with domain verification errors

📋 Get Emails from Database

GET /api/emails

Retrieve emails from the database with pagination and filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page
`status`	string	-	Filter: valid, format_error, verification_error
`category`	string	-	Filter by demographic category

Example Request

curl "https://emailsvalid.com/api/emails?page=1&status=valid&category=tech_professional"
        

✅ Success Response

{
  "total": 156,
  "page": 1,
  "per_page": 50,
  "emails": [
    {
      "id": 1,
      "email": "developer@startup.io",
      "validation_status": "valid",
      "demographic_category": "tech_professional",
      "confidence_score": 0.92
    }
  ]
}
            

📊 Get Statistics

GET /api/stats

Get overall statistics and demographic breakdown.

✅ Success Response

{
  "total_emails": 5420,
  "valid_emails": 4890,
  "format_errors": 230,
  "verification_errors": 300,
  "enriched_emails": 4650,
  "category_breakdown": {
    "tech_professional": 1250,
    "business_professional": 980,
    "consumer": 1500,
    "education_professional": 420
  }
}
            

📥 Export Valid Emails

GET /export/all-valid

Export all valid emails from the database as a CSV file.

Returns a downloadable CSV file with columns: Email, Category, Subcategory, Confidence, Source, Date Added

GET /download/template

Download a CSV template for bulk uploads.

🎯 Demographic Categories

The AI enrichment system categorizes emails into the following demographic profiles:

Professional Categories

Personal Categories

Organizational Categories

⚠️ Error Handling

Validation Error Categories

Category	Description	Examples
`format`	Email syntax is invalid	Invalid syntax, consecutive dots, missing @
`verification`	Domain cannot receive email	No MX records, DNS timeout, domain not found

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Missing or invalid parameters
`404`	Not Found - Job ID or resource not found
`500`	Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}
        

🚀 Ready to get started?
Head to the Home page to validate your first email, or try a bulk upload!