Batch Check API — Emailyze

Endpoint

POST /v1/check/batch/

The batch check endpoint verifies multiple email addresses or domains in a single request. It is designed for list cleaning, bulk jobs, and offline processing workflows. Each request is limited to 1,000 emails. Results are returned in the same order as the input, with duplicates removed automatically.

Request Body

| Field | Type | Required | Description | |---------|--------|----------|-------------| | emails| array | Yes | Array of strings. Each element is an email address or domain. Maximum 1,000 elements. |

The request body must be valid JSON with a Content-Type of application/json.

Request Example

Using curl with header authentication:

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user1@tempmail.com", "user2@gmail.com", "user3@example.com"]}' \
  "https://api.emailyze.xyz/v1/check/batch/"

Using query parameter authentication:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user1@tempmail.com", "user2@gmail.com"]}' \
  "https://api.emailyze.xyz/v1/check/batch/?key=YOUR_API_KEY"

Larger batch (up to 1000 emails):

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["a@x.com", "b@y.com", "c@z.com", ...]}' \
  "https://api.emailyze.xyz/v1/check/batch/"

Response Schema

A successful response (HTTP 200) is a JSON object with:

| Field | Type | Description | |---------------------|--------|-------------| | results | array | Array of result objects, one per input email. | | processed | number | Number of unique emails processed (after deduplication). | | cached | number | Reserved for future use; currently 0. | | processing_time_ms| number | Total processing time in milliseconds. |

Each element in results has the same structure as a single check response. Invalid or malformed emails return a result with error: "Invalid format" and is_disposable: false, risk_score: 0.

Result Format

Each result object includes:

| Field | Type | Description | |-------------------|---------|-------------| | email | string | The input email or domain. | | domain | string | Extracted domain, or null if invalid. | | is_disposable | boolean | true if disposable. | | provider_type | string | disposable, personal, freemail, masked, or unknown. | | risk_score | number | 0–100. | | mx_valid | boolean | true if domain has valid MX records. | | mx_provider | string | Provider or null. | | local_part_type | string | role, plus_addressing, numerical, standard, or null. | | catch_all | boolean | true/false/null. | | syntax | object | { domain, username, is_valid_syntax, suggestion }. | | smtp | object | can_connect_smtp, has_full_inbox, is_catch_all, is_deliverable, is_disabled. | | error | string | null on success; or "Invalid format" for invalid input. |

Note: Batch processing does not support the verify parameter. SMTP deliverability checks are not performed for batch requests. Use single check with verify=true when deliverability is required.

Example Response

{
  "results": [
    {
      "email": "user1@tempmail.com",
      "domain": "tempmail.com",
      "is_disposable": true,
      "provider_type": "disposable",
      "risk_score": 92.5,
      "mx_valid": true,
      "mx_provider": null,
      "local_part_type": "standard",
      "catch_all": false,
      "syntax": {
        "domain": "tempmail.com",
        "username": "user1",
        "is_valid_syntax": true,
        "suggestion": null
      },
      "smtp": {
        "can_connect_smtp": true,
        "has_full_inbox": null,
        "is_catch_all": false,
        "is_deliverable": null,
        "is_disabled": null
      },
      "error": null
    },
    {
      "email": "user2@gmail.com",
      "domain": "gmail.com",
      "is_disposable": false,
      "provider_type": "freemail",
      "risk_score": 0.0,
      "mx_valid": true,
      "mx_provider": "google",
      "local_part_type": "standard",
      "catch_all": null,
      "syntax": {
        "domain": "gmail.com",
        "username": "user2",
        "is_valid_syntax": true,
        "suggestion": null
      },
      "smtp": {
        "can_connect_smtp": true,
        "has_full_inbox": null,
        "is_catch_all": null,
        "is_deliverable": null,
        "is_disabled": null
      },
      "error": null
    },
    {
      "email": "invalid-format",
      "domain": null,
      "is_disposable": false,
      "provider_type": "unknown",
      "risk_score": 0.0,
      "mx_valid": false,
      "mx_provider": null,
      "local_part_type": null,
      "catch_all": null,
      "syntax": {
        "domain": null,
        "username": null,
        "is_valid_syntax": false,
        "suggestion": null
      },
      "smtp": {
        "can_connect_smtp": false,
        "has_full_inbox": null,
        "is_catch_all": null,
        "is_deliverable": null,
        "is_disabled": null
      },
      "error": "Invalid format"
    }
  ],
  "processed": 3,
  "cached": 0,
  "processing_time_ms": 156
}

Deduplication and Ordering

The API automatically deduplicates the input array. If you send ["a@x.com", "b@y.com", "a@x.com"], the response contains three results: the first and third correspond to a@x.com, and the second to b@y.com. Order is preserved. Duplicates are processed once and the same result is returned for each occurrence. This behavior reduces redundant lookups while keeping the response aligned with your input order.

Error Responses

| Status | Condition | Response Body | |--------|-----------|---------------| | 400 | emails is not an array | {"error": "emails must be an array"} | | 400 | More than 1,000 emails | {"error": "Maximum batch size is 1000"} | | 401 | Missing or invalid API key | {"detail": "Missing API key. Provide X-API-Key header or key query parameter."} or {"detail": "Invalid or inactive API key."} | | 429 | Rate limit exceeded | {"detail": "Request was throttled."} |

Best Practices

Chunk large lists — For lists exceeding 1,000 emails, split into multiple batch requests. Use a delay between requests if you approach rate limits.
Filter invalid input first — Basic syntax validation before sending reduces unnecessary API calls and improves throughput.
Use CSV bulk for very large lists — For tens of thousands of emails, consider the CSV bulk upload feature for asynchronous processing and downloadable results.
Handle errors — Check the error field in each result. Emails with error: "Invalid format" should be treated as unverified.

Throughput and Latency

Batch processing time scales roughly linearly with the number of unique domains. A request with 100 emails might complete in 150–300 ms; 1,000 emails may take 1–3 seconds depending on cache hit rates. Domains already in our cache return faster. Invalid or duplicate emails still count toward processed but add minimal overhead. For time-sensitive workflows, consider splitting large lists into smaller batches and processing them in parallel, respecting rate limits.

Integration Example

A typical list-cleaning workflow: read emails from a CSV or database, chunk into arrays of 1,000, and POST each chunk to the batch endpoint. Parse the results array and update your records with is_disposable, risk_score, and provider_type. Filter out disposables before sending campaigns, or flag high-risk addresses for manual review. The error field identifies invalid addresses that should be corrected or removed from your list.