Skip to main content

Bulk Email Validation

Bulk email validation allows you to validate large lists of email addresses by uploading CSV files. This is perfect for cleaning existing email databases, processing mailing lists, and validating large batches of contacts.

What is Bulk Email Validation?​

Bulk email validation is an asynchronous process that validates email addresses from CSV files. Unlike single or batch validation which returns results immediately, bulk validation processes files in the background, making it ideal for large-scale operations.

How It Works​

The bulk validation process follows these steps:

  1. Upload CSV File - Upload a CSV file containing email addresses (max 7MB)
  2. Job Creation - A validation job is created and queued for processing
  3. Background Processing - The system validates emails asynchronously
  4. Status Monitoring - Check the job status to track progress
  5. Download Results - Download validation results in CSV or JSON format when complete

Key Features​

  • Large File Support: Process thousands of email addresses in a single file
  • Asynchronous Processing: Jobs run in the background, no need to wait
  • Flexible Output: Download results as CSV or JSON
  • Filter Options: Download only verified emails or all results
  • Progress Tracking: Monitor job status and see validation progress
  • Original Data Preserved: Results include your original CSV columns plus validation data

When to Use Bulk Validation​

Bulk email validation is ideal for:

  • Large Email Lists: Processing thousands or millions of email addresses
  • Database Cleaning: Validating existing email databases
  • Mailing List Verification: Ensuring your mailing lists are clean before campaigns
  • Data Migration: Validating emails during data imports
  • Periodic Audits: Regularly checking the health of your email database

File Requirements​

File Format​

  • Format: CSV (Comma-Separated Values)
  • Maximum Size: 7MB per file
  • Encoding: UTF-8 recommended

CSV Structure​

Your CSV file can have various formats:

Single Column:

email
[email protected]
[email protected]

Multiple Columns (email column auto-detected):

name,email,company
John Doe,[email protected],Acme Corp
Jane Smith,[email protected],Tech Inc

The API automatically detects the email column in your CSV file.

Validation Process​

Job Status Flow​

  1. QUEUE - Job is queued and waiting to be processed
  2. IN_PROGRESS - Job is currently being processed
  3. COMPLETED - Job has completed successfully
  4. FAILED - Job failed during processing
  5. CANCELED - Job was canceled

Processing Time​

Processing time depends on:

  • Number of email addresses in the file
  • Current system load
  • Complexity of email validation checks

Most jobs complete within minutes, but very large files may take longer.

Getting Started​

To start using bulk email validation:

  1. Create an API Key - Generate an API key from your dashboard

  2. Prepare Your CSV File - Ensure your CSV file meets the requirements

    • Maximum 7MB file size
    • Contains email addresses in a recognizable column

  3. Upload Your File - Use the upload endpoint to submit your file

  4. Monitor Progress - Check the job status periodically

  5. Download Results - Download results when the job is complete

Quick Start Guide​

Step 1: Upload Your File​

curl -X POST "https://api.simplecold.com/api/v1/api-validation/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -F "[email protected]"

Step 2: Check Job Status​

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/JOB_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Step 3: Download Results​

curl -X GET "https://api.simplecold.com/api/v1/api-validation/bulk/JOB_ID/download-result" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -o results.csv

API Endpoints​

The bulk email validation API consists of three endpoints:

1. Upload Email List​

Endpoint: POST /api/v1/api-validation/bulk

Upload a CSV file to start a bulk validation job.

2. Get Validation Status​

Endpoint: GET /api/v1/api-validation/bulk/:id/status

Check the status and progress of a validation job.

3. Download Validation Result​

Endpoint: GET /api/v1/api-validation/bulk/:id/download-result

Download validation results in CSV or JSON format.

Rate Limits​

  • 10 requests per minute per API key
  • Applies to all bulk validation endpoints
  • If exceeded, you'll receive a 429 Too Many Requests response

Response Data​

Validation Results Include​

Each validated email includes:

  • Email Address: The original email address
  • Status: Validation status (ok, invalid, disposable, unknown, etc.)
  • Category: Result category (valid, invalid, risky, unknown)
  • MX Location: Geographic location of mail exchange server
  • Site Location: Geographic location of email provider
  • Site Language: Language of email provider's website
  • Fail Type: Type of failure (temporary, permanent, none)
  • Status Message: Human-readable validation result

Output Formats​

Results can be downloaded in two formats:

  • CSV: Includes original columns plus validation data
  • JSON: Array of email validation objects

Best Practices​

File Preparation​

  • Clean Your Data: Remove duplicates before uploading
  • Validate Format: Ensure CSV is properly formatted
  • Check File Size: Keep files under 7MB limit
  • Use Headers: Include column headers for better organization

Job Management​

  • Store Job IDs: Save job IDs to track your validations
  • Poll Regularly: Check status every 10-30 seconds
  • Handle Errors: Implement error handling for failed jobs
  • Monitor Credits: Track credit usage for large files

Result Processing​

  • Download Promptly: Download results soon after completion
  • Filter Results: Use verifiedOnly parameter to get only valid emails
  • Backup Results: Store downloaded results securely
  • Update Database: Use results to update your email database

Comparison with Other Validation Methods​

FeatureSingle ValidationBatch ValidationBulk Validation
Max Emails150Unlimited
Response TimeImmediateImmediateAsynchronous
File UploadNoNoYes (CSV)
Best ForReal-time checksSmall listsLarge databases

Additional Resources​