Name: Email Validator API: Real-time Syntax, MX, SMTP Verification
Brand: viv-data
SKU: api-viv-data-email-validator
Availability: InStock
Author: API Market

gia ly bui

# Email Validator — Syntax, MX, SMTP Verification

## Overview

The Email Validator API provides a robust, real-time solution for verifying the validity of any email address. It employs a comprehensive three-step process: an RFC-compliant syntax check, an MX record lookup to confirm domain mail acceptance, and an SMTP handshake to verify the actual existence of the mailbox without sending any email. This ensures high accuracy and helps prevent bounces, improve deliverability, and maintain clean contact lists.

## Features

*   **Real-time Validation:** Instantly verify email addresses as they are entered or submitted.
*   **3-Step Verification:**
    *   **Syntax Check:** Ensures the email adheres to RFC standards using rigorous regex validation.
    *   **MX Lookup:** Queries DNS records to confirm the domain is configured to receive emails.
    *   **SMTP Handshake:** Connects to the mail server to verify the existence of the mailbox.
*   **No Email Sent:** The validation process does not send any emails, making it GDPR-friendly and non-intrusive.
*   **Catch Invalid Emails:** Detects typos (e.g., `gmial.com` instead of `gmail.com`), disposable email addresses, and emails belonging to dead domains.
*   **Zero External Dependencies:** Built with pure Python standard library for reliability and performance.
*   **Bounce Prevention:** Significantly reduces bounce rates by identifying invalid email addresses before sending.
*   **Free Tier Available:** Start with 1,000 free validations per month.

## Use Cases

The Email Validator API is essential for any business or application that relies on accurate email communication.

*   **Email Marketing & CRM:** Improve email deliverability, reduce bounce rates, and maintain high sender reputation by cleaning your mailing lists of invalid and inactive email addresses. Segment and target your audience more effectively.
*   **User Registration & Lead Generation:** Prevent fake sign-ups, reduce spam, and ensure that new users provide valid contact information, leading to higher quality leads and more engaged users.
*   **E-commerce & Payments:** Minimize fraud by validating customer email addresses during checkout. Ensure critical transactional emails (order confirmations, shipping updates, password resets) reach their intended recipients.
*   **Data Hygiene & Compliance:** Regularly cleanse existing customer and prospect databases to ensure data accuracy and compliance with data protection regulations. Avoid wasted resources on sending emails to non-existent addresses.
*   **Application Development:** Integrate real-time email validation directly into your web or mobile applications, forms, and backend systems to ensure data quality at the point of entry and enhance user experience.

    

## API Documentation

### Base URL

All API requests should be made to:
`https://prod.api.market/api/v1/viv-data/email-validator`

### Authentication

Authentication is handled via an API key. Include your API key in the request header:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Replace `YOUR_API_MARKET_KEY` with your actual API key.

### Synchronous Processing

This API operates in a synchronous processing mode. This means that when you send a request to an endpoint, the API processes the request immediately and returns the final result directly in the response. There are no job IDs to track, no polling required, and no separate status checks. A single request will yield the complete validation result.

For typical email validation requests, the response time is very quick. However, clients should implement a reasonable request timeout (e.g., 30-60 seconds) to handle any potential network latency or transient server issues.

### Endpoints

#### Validate a single email address

**GET /validate**

Validates a single email address using the 3-step verification process.

**Parameters:**

| Name    | In    | Type   | Required | Description                 |
| :------ | :---- | :----- | :------- | :-------------------------- |
| `email` | query | string | true     | Email address to validate.  |

**Example Request:**

```bash
curl "https://prod.api.market/api/v1/viv-data/email-validator/validate?email=test@gmail.com" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**

```json
{
  "email": "test@gmail.com",
  "valid": true,
  "reason": "Mailbox exists",
  "domain": "gmail.com",
  "mx_server": "gmail-smtp-in.l.google.com"
}
```

**Example Response (200 OK - Invalid Email):**

```json
{
  "email": "invalid@domain.coom",
  "valid": false,
  "reason": "MX records not found",
  "domain": "domain.coom",
  "mx_server": null
}
```

#### Validate multiple emails at once

**POST /validate-batch**

Validates multiple email addresses in a single request. The request body should be a JSON array of email strings. The response will be a JSON array of validation results, corresponding to the order of emails in the request.

**Request Body:**

```json
[
  "email1@example.com",
  "email2@example.com"
]
```

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/viv-data/email-validator/validate-batch" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '["test@gmail.com", "invalid@domain.coom"]'
```

**Example Response (200 OK):**

```json
[
  {
    "email": "test@gmail.com",
    "valid": true,
    "reason": "Mailbox exists",
    "domain": "gmail.com",
    "mx_server": "gmail-smtp-in.l.google.com"
  },
  {
    "email": "invalid@domain.coom",
    "valid": false,
    "reason": "MX records not found",
    "domain": "domain.coom",
    "mx_server": null
  }
]
```

## Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

*   **200 OK:** The request was successful, and the response body contains the requested data (e.g., validation results).
*   **201 Created:** (Not typically used by this API but included for completeness) A resource was successfully created.
*   **400 Bad Request:** The request was malformed, or invalid input parameters were provided. Check your request body or query parameters for errors.
*   **401 Unauthorized:** Your request is missing a valid API key or the provided key is incorrect. Ensure the `x-api-market-key` header is present and correct.
*   **403 Forbidden:** Your API key is valid, but you do not have permission to access the requested resource or perform the action. This could indicate insufficient permissions for your plan.
*   **404 Not Found:** The requested endpoint or resource does not exist. Verify the API endpoint URL.
*   **422 Unprocessable Entity:** The request was well-formed but could not be processed due to semantic errors in the input (e.g., an email address that doesn't conform to basic string requirements, though this API is designed to handle invalid formats and return a `valid: false` result).
*   **429 Too Many Requests:** You have exceeded your API rate limits. Refer to the Rate Limits section for details.
*   **500 Internal Server Error:** An unexpected error occurred on the API server. This is typically a transient issue; please report persistent errors to support.
*   **503 Service Unavailable:** The server is temporarily unable to handle the request, possibly due to maintenance or overload. Retry the request after a short delay.

## Rate Limits

The Email Validator API enforces rate limits to ensure fair usage and service stability. Your rate limit is determined by your subscription plan:

*   **Basic:** 1,000 validations per month
*   **Pro:** 10,000 validations per month
*   **Ultra:** 50,000 validations per month

Usage is tracked based on your `x-api-market-key`. If you exceed your plan's rate limit, you will receive a `429 Too Many Requests` HTTP status code. To avoid hitting rate limits, consider upgrading your plan or optimizing your usage by:

*   Using the batch validation endpoint for multiple emails.
*   Caching results for frequently validated and known-valid email addresses.

## Error Handling

Effective error handling is crucial for building robust applications. This section outlines how to interpret and respond to errors from the Email Validator API.

**Interpreting Error Responses:**

When an error occurs, the API will return an appropriate HTTP status code (see [Status Codes](#status-codes) above) and, for most client-side errors, a JSON response body containing more details about the error.

Example of a `400 Bad Request` or `422 Unprocessable Entity` error:

```json
{
  "detail": [
    {
      "loc": [
        "query",
        "email"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

**Common Errors and How to Resolve Them:**

*   **401 Unauthorized (Missing or Invalid API Key):**
    *   **Issue:** The `x-api-market-key` header is either missing or contains an incorrect/expired key.
    *   **Resolution:** Ensure your API key is correctly included in the `x-api-market-key` header for all requests. Double-check for typos.
*   **400 Bad Request / 422 Unprocessable Entity (Invalid Input):**
    *   **Issue:** The `email` query parameter for `/validate` is missing, or the JSON body for `/validate-batch` is malformed or contains non-string elements.
    *   **Resolution:** Review the API documentation for the specific endpoint you are calling. Ensure all required parameters are present and correctly formatted according to their data types.
*   **429 Too Many Requests (Rate Limit Exceeded):**
    *   **Issue:** You have sent too many requests within your allowed rate limit.
    *   **Resolution:** Implement a delay between your requests, utilize batch processing for multiple validations, or consider upgrading your API plan.
*   **5xx Server Errors (Internal Server Error, Service Unavailable):**
    *   **Issue:** These indicate transient problems on the API server.
    *   **Resolution:** Implement a retry mechanism with an exponential backoff strategy (e.g., wait 1 second, then 2, then 4) for these errors. If the problem persists, contact support.

**Recommended Retry Strategies:**

For transient errors like `5xx` status codes or network interruptions, a retry mechanism can improve the robustness of your application.

*   **Exponential Backoff:** If a request fails, wait a small amount of time (e.g., 1 second) and retry. If it fails again, double the wait time (e.g., 2 seconds), and so on, up to a maximum number of retries or a maximum delay.
*   **Jitter:** Add a small random amount of time to each backoff interval to prevent many clients from retrying simultaneously and overwhelming the server.
*   **Idempotency:** For `POST` requests, ensure your API calls are idempotent where possible to prevent unintended side effects if a request is retried and successfully processed multiple times. For this API, the `POST /validate-batch` is safe to retry if the initial response is unclear, as validation itself is a read-only operation.

## Implementation Guide

This guide demonstrates how to integrate the Email Validator API into your applications using various programming languages. Since this API is synchronous, a single request will return the final validation result.

### Example Code

Replace `YOUR_API_MARKET_KEY` with your actual API key.

#### JavaScript

```javascript
// JavaScript example for synchronous API calls
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/email-validator";

async function validateEmail(email) {
  try {
    const response = await fetch(`${baseUrl}/validate?email=${encodeURIComponent(email)}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const result = await response.json();
    console.log(`Validation for ${email}:`, result);
    return result;
  } catch (error) {
    console.error("Error validating email:", error);
    throw error;
  }
}

async function validateBatch(emails) {
  try {
    const response = await fetch(`${baseUrl}/validate-batch`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify(emails)
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const results = await response.json();
    console.log("Batch validation results:", results);
    return results;
  } catch (error) {
    console.error("Error validating emails in batch:", error);
    throw error;
  }
}

// --- Usage Examples ---
(async () => {
  console.log("--- Single Email Validation ---");
  await validateEmail("test@gmail.com");
  await validateEmail("invalid@domain.coom");
  await validateEmail("user@example.com");

  console.log("\n--- Batch Email Validation ---");
  const emailsToValidate = [
    "example1@gmail.com",
    "john.doe@notrealdomain.xyz",
    "alice@yahoo.com",
    "disposable@mailinator.com"
  ];
  await validateBatch(emailsToValidate);
})();
```

#### Python

```python
# Python example for synchronous API calls
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/email-validator"

def validate_email(email):
    """Validates a single email address."""
    headers = {
        "x-api-market-key": API_KEY
    }
    
    try:
        response = requests.get(
            f"{BASE_URL}/validate",
            headers=headers,
            params={"email": email},
            timeout=30 # Client-side timeout for the request
        )
        response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
        
        result = response.json()
        print(f"Validation for {email}: {json.dumps(result, indent=2)}")
        return result
    except requests.exceptions.RequestException as e:
        print(f"Error validating email {email}: {e}")
        if e.response:
            print(f"Response content: {e.response.text}")
        return None

def validate_batch(emails):
    """Validates multiple email addresses in a batch."""
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    
    try:
        response = requests.post(
            f"{BASE_URL}/validate-batch",
            headers=headers,
            json=emails,
            timeout=60 # Client-side timeout for batch requests
        )
        response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
        
        results = response.json()
        print(f"Batch validation results: {json.dumps(results, indent=2)}")
        return results
    except requests.exceptions.RequestException as e:
        print(f"Error validating emails in batch: {e}")
        if e.response:
            print(f"Response content: {e.response.text}")
        return None

# --- Usage Examples ---
if __name__ == "__main__":
    print("--- Single Email Validation ---")
    validate_email("test@gmail.com")
    validate_email("invalid@domain.coom")
    validate_email("user@example.com")

    print("\n--- Batch Email Validation ---")
    emails_to_validate = [
        "example1@gmail.com",
        "john.doe@notrealdomain.xyz",
        "alice@yahoo.com",
        "disposable@mailinator.com"
    ]
    validate_batch(emails_to_validate)
```

#### cURL

### Validate a single email address

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/email-validator/validate?email=test@gmail.com" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response**

```json
{
  "email": "test@gmail.com",
  "valid": true,
  "reason": "Valid email address"
}
```

---

### Validate an invalid email address

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/email-validator/validate?email=invalid@domain.coom" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response**

```json
{
  "email": "invalid@domain.coom",
  "valid": false,
  "reason": "Domain does not exist"
}
```

---

### Validate multiple email addresses

```bash
curl -X POST "https://prod.api.market/api/v1/viv-data/email-validator/validate-batch" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '[
    "example1@gmail.com",
    "john.doe@notrealdomain.xyz",
    "alice@yahoo.com"
  ]'
```

**Example Response**

```json
[
  {
    "email": "example1@gmail.com",
    "valid": true
  },
  {
    "email": "john.doe@notrealdomain.xyz",
    "valid": false
  },
  {
    "email": "alice@yahoo.com",
    "valid": true
  }
]
```

### Performance Optimization

To maximize the efficiency of your API usage and potentially minimize costs:

*   **Utilize Batch Processing:** For validating multiple email addresses, prefer the `/validate-batch` endpoint over individual calls to `/validate`. This reduces network overhead and can lead to faster overall processing.
*   **Cache Valid Results:** If you frequently validate the same email addresses and they are known to be valid and stable (e.g., corporate emails), consider caching their validation results locally. Revalidate them periodically rather than on every check.
*   **Filter Basic Syntax First:** For very large lists, perform a rudimentary client-side regex check for email syntax before sending to the API. While the API includes a robust syntax check, filtering clearly malformed emails can save API calls.
*   **Error Handling for Invalid Inputs:** Ensure your application properly handles `4xx` errors to avoid unnecessary retries on persistently invalid requests.

## FAQ

**Q: What is real-time email validation?**

A: Real-time email validation means the email address is checked at the exact moment it's provided (e.g., during sign-up, form submission), giving instant feedback on its validity.

**Q: How accurate is the Email Validator API?**

A: The API employs a 3-step verification process (syntax, MX, SMTP handshake) for high accuracy. While no validation service can guarantee 100% accuracy due to external factors, this API provides a very reliable assessment of an email's deliverability.

**Q: Does the API send emails during validation?**

A: No, the API performs an SMTP handshake without actually sending an email. This makes the process non-intrusive and GDPR-friendly.

**Q: What does "partial validation" mean?**

A: Some mail servers disable SMTP VRFY commands for privacy or security reasons. In such cases, the API might not be able to confirm exact mailbox existence, leading to a "partial validation" status, where syntax and MX records are confirmed, but the final mailbox check cannot be completed.

**Q: How does the API handle disposable email addresses?**

A: The API flags disposable email domains (e.g., `mailinator.com`) as invalid, helping you filter out temporary or fraudulent sign-ups.

**Q: What happens if a mail server blocks SMTP VRFY?**

A: If a mail server blocks the SMTP VRFY command, the API will still perform the syntax and MX record checks. The `reason` field in the response will indicate that the mailbox check could not be completed, and `valid` might be `null` or `false` depending on the confidence level, signaling a "partial validation."

**Q: How does the API handle common typos like `gmial.com`?**

A: The API's MX lookup and SMTP handshake steps are designed to identify domains that do not exist or do not accept mail, effectively catching such typos and flagging them as invalid.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Validate email addresses in real-time with the Email Validator API. Perform syntax, MX, and SMTP checks to verify mailbox existence and prevent bounces. GDPR fr