Get your API key

Make your first email validation request in under 2 minutes.

1. Generate an API Key

To start, create an API key for your application. You can create multiple keys from the same account:

1. Create a account (sign up here)
2. Visit the API Settings page
3. Click "Generate API Key"
4. Enter a name and select sandbox as the API Key type
5. Click "Generate" and copy the key

In sandbox mode, only 3 specific test emails return real classifications — all others default to white. See Sandbox & IP Blocks for the details on sandbox mode.

2. Add the API Key to Your Environment

Create a .env file in your project root:

USER_CLEANING_API_KEY=your-api-key

This keeps your API key out of source code. You can find framework-specific setup in Framework Integrations.

3. Test with curl

Single email check:

curl -X POST "https://api.user.cleaning/v1/external-api-requests/check-email?email=test@tempmail.com" \
  -H "X-API-Key: your-api-key"

Batch check — upload a local CSV file:

curl -X POST "https://api.user.cleaning/v1/external-api-requests/batch-check-emails" \
  -H "X-API-Key: your-api-key" \
  -F "file=@emails.csv" \
  -F "project_name=my-list" \
  -F "deduplicate=true"

The file must contain an email column and be CSV, XLSX, or TSV. The response contains a task_id — use it to download or poll for results. See Batch Verification for the full workflow.

4. Check the Response

A successful response for a single email check looks like this:

{
  "email": "test@tempmail.com",
  "domain": "tempmail.com",
  "category": "black",
  "mx_record": "unknown",
  "premium": "False",
  "domain_age": "15010",
  "date_added": "01.01.2023",
  "type": "disposable",
  "remaining_attempts_before_ban": 4
}

The category field tells you what to do:

You can find a detailed explanation of all output fields on the Categories Reference page.

5. Handle the Response in Your Code

Here's a minimal example in Python:

import requests

response = requests.post(
    "https://api.user.cleaning/v1/external-api-requests/check-email",
    params={"email": "test@tempmail.com"},
    headers={"X-API-Key": "your-api-key"}
)

if response.json()["category"] == "black":
    raise ValueError("Disposable emails are not allowed")

That's it — one API call and you have cleaner users, lower bounce rates, and fewer headaches.

Next Steps

• Sandbox & IP Blocks — Configure the Sandbox mode and IP-based blocks
• Categories Reference — Understand what each result mean
• Framework Integrations — Add to Django, FastAPI, Express, etc.
• API Reference — Full endpoint documentation