Name: Disposable Email Detector API: Validate Emails & Prevent Spa
Brand: ozhaya
SKU: api-ozhaya-disposable-email-detector
Availability: InStock
Author: API Market

Joevin Shanto

# Disposable Email Detector

## Overview

The Disposable Email Detector API is a powerful tool designed to help you identify and filter out temporary or disposable email addresses. It validates email structure, checks for disposable addresses, confirms the existence of MX records, and flags role accounts, enabling you to improve data quality, reduce spam, and enhance your overall email communication strategy. The API also caches results for repeat lookups, ensuring low latency and efficient processing.

## Features

*   **Email Structure Validation:** Verifies if an email address adheres to the correct format.
*   **Disposable Email Detection:** Identifies and flags disposable or temporary email addresses.
*   **Result Caching:** Caches results for faster processing on repeat checks.
*   **Role Account Detection:** Flags role-based email accounts (e.g., admin@, noreply@).
*   **MX Record Verification:** Confirms the existence of MX records, indicating that the domain can receive emails.
*   **Bulk Validation:** Supports validating multiple email addresses in a single request.

## Use Cases

*   **E-commerce: Prevent Fraudulent Orders**  By identifying disposable email addresses during checkout, e-commerce platforms can reduce the risk of fraudulent orders and protect their revenue.
*   **SaaS: Improve Trial Conversion Rates**  SaaS companies can use the API to block disposable emails during free trial sign-up, ensuring that only legitimate users are granted access to the platform. This improves the quality of leads and increases the likelihood of converting trial users into paying customers.
*   **Financial Services: Enhance KYC/AML Compliance**  Financial institutions can integrate the API into their Know Your Customer (KYC) and Anti-Money Laundering (AML) processes to verify the validity of email addresses provided by customers, reducing the risk of identity theft and financial fraud.
*   **Online Gaming: Reduce Bot Activity** Online gaming platforms can use the API to identify and block disposable email addresses used by bots and fake accounts, creating a more fair and enjoyable gaming experience for legitimate players.
*   **Healthcare: Secure Patient Communications** Healthcare providers can use the API to validate patient email addresses, ensuring that sensitive medical information is sent to the correct recipients and reducing the risk of data breaches.

## Pricing

*   1 API unit equals 1 email validated (single or bulk).
*   GET requests to check prediction status (GET /api/v1/magicapi/disposable-email-detector/predictions/{id}) are free and don't count toward API unit usage.
*   Different pricing tiers are available based on usage volume:

    | Plan   | Price  | Requests/month |
    | :----- | :----- | :------------- |
    | Free   | \$0    | 500            |
    | Pro    | \$4.99 | 10,000         |
    | Ultra  | \$9.99 | 100,000        |

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/magicapi/disposable-email-detector`

### Authentication

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

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

### Endpoints

#### 1. Validate Email (GET)

Validates a single email address.

**Endpoint:** `/validate`

**Method:** `GET`

**Query Parameters:**

*   `email` (string, required): The email address to validate.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/disposable-email-detector/validate?email=test@example.com" \
-H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response:**

```json
{
  "email": "test@example.com",
  "valid_email_structure": true,
  "mx_records": true,
  "not_disposable": true,
  "valid_email": true
}
```

**Response Fields:**

| Field                  | Type    | Description                                           |
| :--------------------- | :------ | :---------------------------------------------------- |
| email                  | string  | The email address being validated.                    |
| valid_email_structure  | boolean | Whether the email format is correct.                  |
| mx_records             | boolean | Whether the domain has mail servers.                  |
| not_disposable         | boolean | Whether the email is NOT disposable.                  |
| valid_email            | boolean | Overall valid (all fields are true).                 |

#### 2. Validate Bulk (POST)

Validates multiple email addresses in a single request.

**Endpoint:** `/validate-bulk`

**Method:** `POST`

**Request Body:**

```json
{
  "emails": ["test1@example.com", "test2@example.com"]
}
```

**Content-Type:** `application/json`

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/disposable-email-detector/validate-bulk" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{"emails": ["test1@example.com", "test2@example.com"]}'
```

**Example Response:**

```json
[
  {
    "email": "test1@example.com",
    "valid_email_structure": true,
    "mx_records": true,
    "not_disposable": true,
    "valid_email": true
  },
  {
    "email": "test2@example.com",
    "valid_email_structure": true,
    "mx_records": false,
    "not_disposable": true,
    "valid_email": false
  }
]
```

**Response Fields (for each email in the array):**

| Field                  | Type    | Description                                           |
| :--------------------- | :------ | :---------------------------------------------------- |
| email                  | string  | The email address being validated.                    |
| valid_email_structure  | boolean | Whether the email format is correct.                  |
| mx_records             | boolean | Whether the domain has mail servers.                  |
| not_disposable         | boolean | Whether the email is NOT disposable.                  |
| valid_email            | boolean | Overall valid (all fields are true).                 |

## Status Codes

*   `200 OK`: Request successful.
*   `400 Bad Request`: Invalid input parameters or malformed request.  This can occur if the JSON is malformed in the request body for `/validate-bulk`.
*   `401 Unauthorized`: Missing or invalid API key. Ensure that the `x-api-market-key` header is present and contains a valid API key.
*   `403 Forbidden`: Valid API key but insufficient permissions.  (Currently not applicable)
*   `404 Not Found`: Resource not found. Double-check the endpoint URL.
*   `429 Too Many Requests`: Rate limit exceeded.  Reduce the number of requests per minute.
*   `500 Internal Server Error`: Server-side error.  Contact support if this persists.
*   `503 Service Unavailable`: Service temporarily unavailable.  Retry the request later.

## Rate Limits

| Plan   | Requests per minute |
| :----- | :------------------ |
| Free   | 20                  |
| Pro    | 120                 |
| Ultra  | 240                 |

If you exceed the rate limit, you will receive a `429 Too Many Requests` error. Implement retry logic to handle this error. Consider using an exponential backoff strategy to avoid overwhelming the API.

## Error Handling

The API returns error responses in JSON format with a corresponding HTTP status code. The JSON body typically includes an error object with details about the error.

**Example Error Response:**

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

Common errors and how to resolve them:

*   **Missing API Key:** Ensure the `x-api-market-key` header is present in all requests.
*   **Invalid API Key:** Verify that the API key is correct and active.
*   **Invalid Email Format:** The `email` parameter must be a valid email address format.
*   **Rate Limit Exceeded:** Reduce the number of requests per minute.

Recommended retry strategies for transient errors (e.g., `503 Service Unavailable`):

*   Implement exponential backoff with a maximum retry count.
*   Introduce a random jitter to avoid synchronized retries.

## Implementation Guide

### Example Code

#### JavaScript

```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/disposable-email-detector";

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

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

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

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

// Example usage
async function runExample() {
  try {
    const singleEmailResult = await validateEmail("test@example.com");
    console.log("Single Email Validation Result:", singleEmailResult);

    const bulkEmailResult = await validateBulkEmails(["test1@example.com", "test2@example.com"]);
    console.log("Bulk Email Validation Result:", bulkEmailResult);
  } catch (error) {
    console.error("Example Error:", error);
  }
}

runExample();
```

#### Python

```python
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/disposable-email-detector"

def validate_email(email):
    headers = {
        "x-api-market-key": API_KEY
    }
    response = requests.get(f"{BASE_URL}/validate?email={email}", headers=headers)

    if response.status_code != 200:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return response.json()

def validate_bulk_emails(emails):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    data = {"emails": emails}
    response = requests.post(f"{BASE_URL}/validate-bulk", headers=headers, json=data)

    if response.status_code != 200:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return response.json()

# Example usage
try:
    single_email_result = validate_email("test@example.com")
    print("Single Email Validation Result:", single_email_result)

    bulk_email_result = validate_bulk_emails(["test1@example.com", "test2@example.com"])
    print("Bulk Email Validation Result:", bulk_email_result)

except Exception as e:
    print("Example Error:", e)
```

#### cURL

```bash
# Validate Single Email
curl -X GET "https://prod.api.market/api/v1/magicapi/disposable-email-detector/validate?email=test@example.com" \
-H "x-api-market-key: YOUR_API_MARKET_KEY"

# Validate Bulk Emails
curl -X POST "https://prod.api.market/api/v1/magicapi/disposable-email-detector/validate-bulk" \
-H "Content-Type: application/json" \
-H "x-api-market-key: YOUR_API_MARKET_KEY" \
-d '{"emails": ["test1@example.com", "test2@example.com"]}'
```

### Performance Optimization

*   Use bulk validation to minimize the number of API calls.
*   Cache results locally where appropriate.  Be mindful of data freshness requirements.
*   Monitor API usage and adjust plan accordingly.

## FAQ

**Q: What happens if I exceed my rate limit?**

A: You will receive a `429 Too Many Requests` error. You should implement retry logic with exponential backoff to handle this.

**Q: How accurate is the disposable email detection?**

A: The API uses multiple data sources and algorithms to provide a high degree of accuracy. However, no system is perfect, and some disposable email addresses may still slip through.

**Q: What is considered a valid email address?**

A: A valid email address must adhere to the standard email format (local-part@domain) and have a resolvable MX record. The API will also check if the domain is on a list of known disposable email providers.

**Q:  Is caching enabled?**

A: Yes, the API caches results for repeat lookups to improve performance.

## 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[at]api.market.


Validate email addresses, detect disposable emails & prevent spam. Improve data quality with our fast & accurate API.

Disposable Email Detector API: Validate Emails & Prevent Spa