API Reference

Disposable Email Detection

Check if an email address belongs to a disposable or temporary email provider

Protect your registration forms and sign-up flows from fake accounts. Disposable email detection helps reduce fraud, improve deliverability, and keep your user base clean by identifying temporary email providers like Guerrilla Mail, Mailinator, and hundreds of others before they enter your system.

blocklist matchingMX record analysisrisk scoringbatch support

Endpoint

POST /v1/email/check
Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.
Open Swagger UI (interactive docs)

Request

{
  "email": "test@guerrillamail.com"
}

Request Fields

FieldTypeDescription
email string Email address to check

Response

{
  "email": "test@guerrillamail.com",
  "domain": "guerrillamail.com",
  "disposable": true,
  "score": 95,
  "reasons": [
    "Domain found in disposable email provider list",
    "Domain has short MX record TTL"
  ],
  "checkedAt": "2026-03-25T14:30:00Z"
}

Response Fields

FieldTypeDescription
email string Email address to check
domain string Domain name extracted from the email
disposable boolean Whether the email is from a disposable provider
score number Risk/confidence score (0-100)
reasons array List of reasons for the classification
checkedAt string Timestamp of when the check was performed

Error Codes

StatusMeaning
200Request completed successfully
400Bad request — invalid or missing parameters
401Missing or invalid X-API-Key header
429Rate limit exceeded — check Retry-After header
500Internal server error

Common Error Scenarios

400 Invalid email format

Request that triggers this:

{"email": "not-an-email"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid Email", "status": 400, "detail": "The value 'not-an-email' is not a valid email address"}

How to fix: Ensure the email field contains a valid email address with an @ symbol and domain.

429 Rate limit exceeded

Request that triggers this:

(after many rapid requests)

Error response:

{"type": "/problems/rate-limit", "title": "Too Many Requests", "status": 429, "detail": "Rate limit exceeded. Try again in 45 seconds"}

How to fix: Implement exponential backoff. Check the Retry-After header for the wait time. Consider upgrading your plan for higher limits.

Code Examples

curl -X POST /v1/email/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "email": "test@guerrillamail.com"
}' 
// Node.js (18+) or modern browser
const response = await fetch("/v1/email/check", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "test@guerrillamail.com"
}),
});

const data = await response.json();
console.log(response.status, data);
import requests

response = requests.post(
    "/v1/email/check",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "email": "test@guerrillamail.com"
},
)

print(response.status_code)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "email": "test@guerrillamail.com"
}`)
	req, _ := http.NewRequest("POST", "/v1/email/check", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}
{
  "name": "disposable_email",
  "description": "Check if an email address belongs to a disposable or temporary email provider",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/email/check",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference