The Emailyze API provides real-time disposable email detection for SaaS signups, e-commerce checkout, email marketing list hygiene, and fraud prevention. Send an email address or domain, and receive structured signals—including is_disposable, risk_score, and provider_type—to block, flag, or segment high-risk addresses. All endpoints return JSON and require authentication via API key.
Every request must include your API key. Obtain a key from the [dashboard](https://app.emailyze.xyz/dashboard) after signing up. Two methods are supported:
Header (recommended) — Pass the key in the X-API-Key header:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.emailyze.xyz/v1/check/?email=test@tempmail.com"Query parameter — Pass the key as the key query parameter:
curl "https://api.emailyze.xyz/v1/check/?email=test@tempmail.com&key=YOUR_API_KEY"The header method is preferred because it avoids logging the key in server access logs. Requests without a valid key receive 401 Unauthorized.
| Environment | Base URL | |-------------|----------| | Production | https://api.emailyze.xyz | | On-premise | Your deployment URL (e.g., https://emailguard.yourcompany.com) |
All endpoint paths are relative to the base URL. Example: GET https://api.emailyze.xyz/v1/check/?email=user@example.com.
| Method | Path | Description | |--------|------|-------------| | GET | /v1/check/ | Single email or domain lookup. Returns signals for one address. | | POST | /v1/check/batch/ | Bulk verification. Up to 1,000 emails per request. | | GET | /v1/download/ | Download the full domain list (JSONL, gzipped) for offline use. | | POST | /v1/feedback/ | Submit feedback (false positive, new domain) to improve accuracy. |
Check one email address or domain. Query parameters:
email (required) — The email to verify (e.g., user@tempmail.com)domain (optional) — Alternatively, check a domain only (e.g., tempmail.com)Example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://api.emailyze.xyz/v1/check/?email=test@tempmail.com"Response (200 OK):
{
"email": "test@tempmail.com",
"domain": "tempmail.com",
"is_disposable": true,
"risk_score": 92,
"provider_type": "disposable"
}See the [single check reference](/docs/check) for full parameter and response documentation.
Verify up to 1,000 emails in one request. Request body (JSON):
{
"emails": ["user1@tempmail.com", "user2@gmail.com", "user3@guerrillamail.com"]
}Example:
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"emails": ["user1@tempmail.com", "user2@gmail.com"]}' \
"https://api.emailyze.xyz/v1/check/batch/"Response (200 OK):
{
"results": [
{
"email": "user1@tempmail.com",
"domain": "tempmail.com",
"is_disposable": true,
"risk_score": 92,
"provider_type": "disposable"
},
{
"email": "user2@gmail.com",
"domain": "gmail.com",
"is_disposable": false,
"risk_score": 5,
"provider_type": "freemail"
}
]
}See the [batch reference](/docs/batch) for limits and error handling.
Retrieve the full domain list for offline or on-premise use. Returns a gzipped JSONL file. Each line is a JSON object with domain metadata.
curl -H "X-API-Key: YOUR_API_KEY" -o domains.jsonl.gz \
"https://api.emailyze.xyz/v1/download/"Report false positives or suggest new disposable domains. Helps improve accuracy over time.
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"email": "user@example.com", "type": "false_positive"}' \
"https://api.emailyze.xyz/v1/feedback/"All successful responses are JSON. Common fields across check endpoints:
disposable, personal, freemail, masked, unknown.See the [signals reference](/docs/signals) for a full explanation of each field.
New to the API? Follow the [quick start guide](/docs/quickstart) to make your first request in under five minutes. It walks through obtaining an API key, making a single check, and interpreting the response.
Rate limits apply per API key. Exact limits depend on your plan; see the dashboard or contact support for details. Responses include rate limit headers when applicable. For high-volume use cases, consider the batch endpoint (1,000 per request) to reduce request count.
The API uses standard HTTP status codes. 200 OK indicates success. 400 Bad Request typically means invalid parameters (e.g., malformed email, empty batch). 401 Unauthorized means missing or invalid API key. 429 Too Many Requests indicates rate limit exceeded. Error responses include a JSON body with an error or detail field describing the issue. Implement retry logic with exponential backoff for transient failures; for 429, respect the Retry-After header when present.
While the API is RESTful and can be called from any HTTP client, community and official SDKs may be available for popular languages (Python, Node.js, etc.). Check the [documentation](https://docs.emailyze.xyz) for current offerings. For quick integrations, curl and requests (Python) or fetch (JavaScript) are sufficient. The API is stateless; no session or persistent connection is required.
For organizations requiring data sovereignty or air-gapped deployments, Emailyze supports on-premise installation. The same API interface is used; only the base URL changes. Contact your account team or see the [on-premise guide](/guides/on-premise) for deployment requirements, licensing, and update procedures. On-premise deployments receive the same domain list updates as the cloud service, ensuring consistent coverage.
Single-check and batch responses share a common structure. Each result object includes at minimum: email, domain, is_disposable, risk_score, and provider_type. Optional fields such as mx_valid and catch_all may appear when available. All timestamps use ISO 8601 format. The download endpoint returns a gzipped JSONL file where each line is a JSON object; parse line-by-line for large files. For full schema documentation, see the [signals reference](/docs/signals) and individual endpoint pages. When integrating, ensure your client handles connection timeouts and retries; the API is designed for low latency, but network conditions vary. Use the batch endpoint for bulk operations to minimize round trips and stay within rate limits. The API is versioned under /v1/; future versions will use new path prefixes to maintain backward compatibility. Deprecation notices will be communicated in advance with migration guidance. All endpoints support CORS for browser-based integrations; use server-side calls when possible to keep API keys secure. For production deployments, configure your HTTP client with appropriate timeouts (e.g., 5–10 seconds) and retry logic for transient network errors. Log API usage for debugging and cost tracking; the dashboard provides usage analytics to monitor consumption against your plan limits.