Skip to main content

Batch Email Validation

Learn how to validate multiple email addresses in a single API request using the SimpleCold Email Validation API.

Authentication​

All API requests require authentication using a Bearer token in the Authorization header. Your API key serves as this Bearer token.

For detailed information on authentication, see the Using API Key guide.

Authorization Header Format​

Include your API key in the Authorization header using the following format:

Authorization: Bearer <your-api-key>

Replace <your-api-key> with your actual API key that you generated from the dashboard.

API Base URL​

All API endpoints are accessed through the following base URL:

https://api.simplecold.com/api/v1

Endpoint​

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

This endpoint validates multiple email addresses in a single request. It's perfect for processing small to medium-sized lists programmatically.

Request Body​

The endpoint accepts a JSON body with the following structure:

FieldTypeRequiredDescription
emailsarrayYesArray of email addresses to validate (max 50)

Request Body Example​

{
  "emails": ["[email protected]", "[email protected]", "[email protected]"]
}

Rate Limits​

  • 10 requests per minute per API key
  • Maximum 50 emails per request
  • If you exceed the rate limit, you'll receive a 429 Too Many Requests response

Request Examples​

Using cURL​

Here's how to validate multiple emails using cURL:

curl -X POST "https://api.simplecold.com/api/v1/api-validation/batch" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'

Success Response (200):

{
  "status": "SUCCESS",
  "payload": [
    {
      "email": "[email protected]",
      "domain": "example.com",
      "status": "ok",
      "statusMessage": "Email address is valid and deliverable",
      "mxLocation": "United States",
      "siteLocation": "United States",
      "siteLanguage": "en",
      "failType": "none"
    },
    {
      "email": "[email protected]",
      "domain": "example.com",
      "status": "invalid",
      "statusMessage": "Email address does not exist",
      "mxLocation": "United States",
      "siteLocation": "United States",
      "siteLanguage": "en",
      "failType": "permanent"
    },
    {
      "email": "[email protected]",
      "domain": "example.com",
      "status": "ok",
      "statusMessage": "Email address is valid and deliverable",
      "mxLocation": "United States",
      "siteLocation": "United States",
      "siteLanguage": "en",
      "failType": "none"
    }
  ]
}

Error Response (400):

{
  "status": "FAILURE",
  "message": "Maximum 50 emails per request is allowed."
}

Error Response (401):

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Error Response (429):

{
  "status": 429,
  "error": "Rate limit exceeded. Maximum 10 requests per minute per API key."
}

Using JavaScript (Fetch API)​

const apiKey = "YOUR_API_KEY_HERE";
const emails = ["[email protected]", "[email protected]", "[email protected]"];

fetch("https://api.simplecold.com/api/v1/api-validation/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ emails }),
})
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "SUCCESS") {
      const results = data.payload;
      console.log(`Validated ${results.length} emails`);

      results.forEach((result) => {
        console.log(`Email: ${result.email}`);
        console.log(`Status: ${result.status}`);
        console.log(`Message: ${result.statusMessage}`);
        console.log("---");
      });

      // Count valid emails
      const validCount = results.filter((r) => r.status === "ok").length;
      console.log(`Valid emails: ${validCount}/${results.length}`);
    } else {
      console.error("Validation failed:", data.message);
    }
  })
  .catch((error) => console.error("Error:", error));

Using Python (requests)​

import requests

api_key = "YOUR_API_KEY_HERE"
url = "https://api.simplecold.com/api/v1/api-validation/batch"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "emails": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    if result.get("status") == "SUCCESS":
        results = result.get("payload")
        print(f"Validated {len(results)} emails")

        for email_result in results:
            print(f"Email: {email_result['email']}")
            print(f"Status: {email_result['status']}")
            print(f"Message: {email_result['statusMessage']}")
            print("---")

        valid_count = len([r for r in results if r['status'] == 'ok'])
        print(f"Valid emails: {valid_count}/{len(results)}")
    else:
        print(f"Error: {result.get('message')}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Response Fields​

The response payload is an array of email validation results. Each result contains the following fields:

FieldTypeDescription
emailstringThe email address that was validated
domainstringThe domain part of the email address
statusstringThe validation status: ok, invalid, disposable, unknown, etc.
statusMessagestringA human-readable description of the validation result
mxLocationstringThe geographic location of the mail exchange server
siteLocationstringThe geographic location of the email provider's website
siteLanguagestringThe language of the email provider's website
failTypestringThe type of failure if applicable: temporary, permanent, or none

Status Values​

Each email result's status field can have the following values:

  • ok: Email address is valid and deliverable
  • invalid: Email address is invalid (syntax error, domain doesn't exist, etc.)
  • disposable: Email address is from a disposable email provider
  • unknown: Unable to determine the validity of the email address
  • syntax_error: Email address has a syntax error

Error Handling​

Common Error Responses​

400 Bad Request​

Maximum Emails Exceeded:

{
  "status": "FAILURE",
  "message": "Maximum 50 emails per request is allowed."
}

Invalid Email Format:

{
  "status": "FAILURE",
  "message": "Invalid email format"
}

401 Unauthorized​

Invalid or Missing API Key:

{
  "status": "FAILURE",
  "message": "Invalid API key"
}

Missing Authorization Header:

{
  "status": "FAILURE",
  "message": "Authorization header is required"
}

Incorrect Format:

{
  "status": "FAILURE",
  "message": "Authorization header must be in format: Bearer <token>"
}

429 Too Many Requests​

Rate Limit Exceeded:

{
  "status": 429,
  "error": "Rate limit exceeded. Maximum 10 requests per minute per API key."
}

Processing Large Lists​

For large email lists (more than 50 emails), you have two options:

  1. Split into multiple batch requests: Process emails in chunks of 50
  2. Use Bulk Email Validation: For very large lists, consider using the Bulk Email Validation endpoint which accepts CSV files

Testing Your Integration​

You can quickly test the batch email validation endpoint:

curl -X POST "https://api.simplecold.com/api/v1/api-validation/batch" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]"
    ]
  }'

A successful response with "status": "SUCCESS" and an array of results indicates your integration is working correctly.

Additional Resources​