Skip to main content

Single Email Validation

Learn how to validate a single email address in real-time 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: GET /api/v1/api-validation/single

This endpoint validates a single email address in real-time. It's perfect for form validation, user signup flows, and real-time email verification.

Request Parameters​

The endpoint accepts the following query parameter:

ParameterTypeRequiredDescription
emailstringYesThe email address to validate

Rate Limits​

  • 100 requests per minute per IP address
  • If you exceed the rate limit, you'll receive a 429 Too Many Requests response

Request Examples​

Using cURL​

Here's how to validate a single email using cURL:

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

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"
  }
}

Error Response (400):

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

Error Response (401):

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

Error Response (429):

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

Using JavaScript (Fetch API)​

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

fetch(
  `https://api.simplecold.com/api/v1/api-validation/single?email=${encodeURIComponent(email)}`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
  }
)
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "SUCCESS") {
      const result = data.payload;
      console.log(`Email: ${result.email}`);
      console.log(`Status: ${result.status}`);
      console.log(`Message: ${result.statusMessage}`);

      // Handle different statuses
      if (result.status === "ok") {
        console.log("Email is valid and deliverable");
      } else if (result.status === "invalid") {
        console.log("Email is invalid");
      } else if (result.status === "disposable") {
        console.log("Email is from a disposable email provider");
      }
    } else {
      console.error("Validation failed:", data.message);
    }
  })
  .catch((error) => console.error("Error:", error));

Using Python (requests)​

import requests

api_key = "YOUR_API_KEY_HERE"
email = "[email protected]"
url = "https://api.simplecold.com/api/v1/api-validation/single"

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

params = {
    "email": email
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    if data.get("status") == "SUCCESS":
        result = data.get("payload")
        print(f"Email: {result['email']}")
        print(f"Status: {result['status']}")
        print(f"Message: {result['statusMessage']}")
    else:
        print(f"Error: {data.get('message')}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Response Fields​

The response payload 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​

The 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​

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 100 requests per minute per API key."
}

Testing Your Integration​

You can quickly test the single email validation endpoint:

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

A successful response with "status": "SUCCESS" indicates your integration is working correctly.

Additional Resources​