# TempMailChecker API — Agent Setup Guide

> Machine-readable API documentation for AI agents and LLMs.
> Human-readable docs: https://tempmailchecker.com/docs

TempMailChecker is a REST API that detects disposable/temporary email addresses
(Mailinator, 10MinuteMail, GuerrillaMail, and 280,000+ other domains).
One GET request, one boolean response. No SDK required.

## Integration instructions for agents

1. The user needs an API key. Free keys (25 checks/day) are issued instantly at
   https://tempmailchecker.com/signup — only an email address is required.
2. Call `GET https://tempmailchecker.com/check` with the `X-API-Key` header on
   every email you want to validate (typically at signup, checkout, or list import).
3. Treat `{"temp": true}` as a disposable address (block or flag it).
   Treat `{"temp": false}` as a legitimate address.
4. Reuse HTTP connections (keep-alive / session objects) — the check then costs
   a single network round-trip. Set a timeout of at least 5 seconds and fail open
   (accept the email) if the API is unreachable, unless the user wants otherwise.
5. Do not hardcode the domain list; it changes daily on the server.

## Base URL

```
https://tempmailchecker.com
```

The legacy `us.tempmailchecker.com` and `asia.tempmailchecker.com` hostnames are
supported aliases of the same service.

## Authentication

Send the API key in the `X-API-Key` request header.

## Endpoints

### GET /check

Check whether an email address (or bare domain) is disposable.

Query parameters (provide exactly one):

| Parameter | Type   | Description                                    |
|-----------|--------|------------------------------------------------|
| email     | string | Full email address; domain is extracted for you |
| domain    | string | Bare domain, e.g. `mailinator.com`              |

Responses:

```json
{"temp": true}    // disposable — block or flag
{"temp": false}   // legitimate
```

Errors:

| Status | Body                                                | Meaning                    |
|--------|-----------------------------------------------------|----------------------------|
| 400    | `{"error": "Missing email or domain parameter"}`    | No email/domain provided   |
| 401    | `{"error": "Invalid API key", "temp": null}`        | Key missing or unknown     |
| 429    | see Rate limits below                               | Quota exhausted            |

### GET /usage

Check current quota usage. The key is passed as a query parameter (no header needed):

```
GET https://tempmailchecker.com/usage?key=YOUR_API_KEY
```

Free plan response (daily quota, resets at midnight UTC):

```json
{"usage_today": 18, "limit": 25, "reset": "midnight UTC"}
```

Paid plan response (monthly quota; `reset` is the renewal date):

```json
{"usage_this_month": 1204, "limit": 3000, "reset": "2026-08-09"}
```

## Rate limits

- Free: 25 requests/day, resets at midnight UTC.
- Paid plans: monthly quotas (Starter 3,000 — Growth 15,000 — Scale 60,000 — Enterprise custom).
- On exceeding the quota, `/check` returns HTTP 429:

```json
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily limit of 25 requests",
  "limit": 25,
  "used": 25,
  "reset": "midnight UTC"
}
```

## Code examples

Python:

```python
import requests

session = requests.Session()  # connection reuse
session.headers["X-API-Key"] = "YOUR_API_KEY"

def is_disposable(email: str) -> bool:
    resp = session.get(
        "https://tempmailchecker.com/check",
        params={"email": email},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()["temp"]
```

JavaScript / Node:

```javascript
async function isDisposable(email) {
  const resp = await fetch(
    `https://tempmailchecker.com/check?email=${encodeURIComponent(email)}`,
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { temp } = await resp.json();
  return temp;
}
```

cURL:

```bash
curl "https://tempmailchecker.com/check?email=user@tempmail.com" \
  -H "X-API-Key: YOUR_API_KEY"
```

PHP:

```php
$ch = curl_init("https://tempmailchecker.com/check?email=" . urlencode($email));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
if ($data["temp"]) echo "Blocked";
```

## Links

- Get an API key: https://tempmailchecker.com/signup
- Human docs: https://tempmailchecker.com/docs
- Status: https://tempmailchecker.com/status
- Pricing: https://tempmailchecker.com/#pricing
- Support: support@tempmailchecker.com