# CleanTempMail API

Base URL: `https://cleantempmail.com`

There is no mailbox-registration step. Fetch the active domains for free, compose a valid address locally or use the optional generator, then query that address and process the returned messages. Request and response examples are documented once in the endpoint reference below.

## Quickstart

1. **Get active domains**: Call /api/domains without a key. This public helper does not consume quota.
2. **Compose or generate**: Build any valid prefix@active-domain locally for free, or spend 1 request on the optional generator.
3. **Check the inbox**: Pass the full address to /api/emails. An empty list is a successful response, not an error.
4. **Read or download**: Use emails[].id to fetch a message and attachments[].id to download a file.

## Authentication

Send your key in the X-API-Key request header. Keep paid keys on your server; do not expose them in browser code, public repositories, query strings, or logs.

```
X-API-Key: YOUR_API_KEY
```

- **Shared test key**: ct-test is a shared, limited key for trying examples. Its usage and remaining quota are shared by everyone and can be checked with the quota endpoint. Use a purchased key for production workloads.
- **When quota is consumed**: A protected request consumes 1 request immediately after its API key is authenticated. Empty inbox results, repeated polling, and handler errors such as an invalid parameter or missing email still count. Public domain listing, quota lookup, and billing endpoints do not consume quota.

### JSON response envelope

JSON endpoints return success plus either data or error. Authenticated protected endpoints also include the updated usage object. Attachment downloads return binary data instead of this JSON envelope.

```json
{
  "success": true,
  "data": { "...": "endpoint-specific data" },
  "usage": {
    "daily_limit": 100,
    "used_today": 7,
    "remaining_today": 93,
    "total_limit": 1000,
    "total_used": 42,
    "remaining_total": 958
  }
}
```

For quota fields, a limit of 0 and a remaining value of -1 mean unlimited. A purchased one-time key normally has a positive total_limit.

## Core endpoints

Endpoints are grouped by the operation they perform. The badge on each endpoint shows whether a successful authentication attempt consumes quota.

### `GET /api/domains`: List active public domains

No API key · no quota. Returns domains currently available for address generation. This public helper does not require an API key and does not consume quota. Private GPTMail domains are excluded.

| Parameter | Required | Description |
| --- | --- | --- |
| `q` | Optional | Case-insensitive substring filter for domain names. |
| `offset` | Optional | Number of matching domains to skip. Defaults to 0. |
| `limit` | Optional | Number of domains to return. Defaults to 1000 and is capped at 2000. |

```bash
curl -sS "https://cleantempmail.com/api/domains?limit=100"
```

```json
{
  "success": true,
  "data": {
    "domains": ["domain-one.example", "domain-two.example"],
    "total": 1832,
    "offset": 0,
    "limit": 100
  }
}
```

### `GET` / `POST /api/generate-email`: Generate a temporary email address

API key · 1 request. GET creates an address with a generated prefix and a random active domain. POST optionally selects a prefix, a domain, or both. The response always returns the final address in data.email.

**Generation is optional — save quota by composing locally**: You do not need to call this endpoint before receiving mail. After obtaining an active domain from /api/domains, combine it locally with any valid prefix, such as qa-run-42@domain-one.example. Mail sent to that address can be queried normally, and composing it locally consumes no quota. Use /api/generate-email only when you want the service to choose or validate the address for you; each call consumes 1 request.

| Parameter | Required | Description |
| --- | --- | --- |
| `prefix` | Optional | Mailbox name before @. Letters, digits, dots, underscores, and hyphens are accepted within the service-configured length. |
| `domain` | Optional | An exact active domain returned by /api/domains. If omitted, the service chooses one randomly. |

```bash
curl -sS \
  -H "X-API-Key: ct-test" \
  "https://cleantempmail.com/api/generate-email"

curl -sS -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"prefix":"qa.user","domain":"your-active-domain.com"}' \
  "https://cleantempmail.com/api/generate-email"
```

If the requested domain is no longer active, the API returns HTTP 409 instead of silently switching to another domain.

### `GET /api/emails?email={address}`: List messages in an inbox

API key · 1 request. Returns up to the latest 500 messages for one public CleanTempMail address. A new or empty inbox returns emails: [] and count: 0.

```bash
curl -sS -G \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "email=alexsmith42@active-domain.example" \
  "https://cleantempmail.com/api/emails"
```

```json
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "66c123example",
        "email_address": "alexsmith42@active-domain.example",
        "from_address": "sender@example.com",
        "subject": "Your verification code",
        "content": "Your code is 123456",
        "html_content": "<p>Your code is <b>123456</b></p>",
        "has_html": true,
        "attachments": [
          { "id": "attachment-id", "filename": "receipt.pdf", "content_type": "application/pdf", "size": 48231 }
        ],
        "timestamp": 1787702400,
        "raw_size": 51984,
        "created_at": "2026-08-25T12:00:00Z"
      }
    ],
    "count": 1
  },
  "usage": { "daily_limit": 100, "used_today": 2, "remaining_today": 98, "total_limit": 1000, "total_used": 2, "remaining_total": 998 }
}
```

### `GET /api/email/{id}`: Fetch one complete message

API key · 1 request. Uses the id returned by /api/emails to retrieve one message, including text/HTML content, headers, timestamps, and attachment metadata. Attachment bytes are not embedded in JSON.

```bash
curl -sS \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://cleantempmail.com/api/email/66c123example"
```

Important email fields:

- `id`: Message ID used by read, attachment, and delete endpoints.
- `email_address`: Inbox address that received the message.
- `from_address`: Parsed sender address.
- `subject`: Parsed message subject.
- `content` / `html_content`: Plain-text and sanitized/renderable HTML representations. Check has_html before preferring HTML.
- `attachments[]`: Attachment metadata: id, filename, content_type, size, and optional content_id. Binary data is downloaded separately.
- `timestamp` / `created_at`: Unix timestamp and ISO 8601 creation time.
- `raw_content` / `headers` / `raw_size`: Raw message/header data when stored, plus the original message size in bytes.

### `GET /api/email/{id}/attachment/{attachmentID}`: Download an attachment

API key · 1 request. Download one attachment as a binary file. Use the email id and an attachments[].id value returned by GET /api/email/{id}. Each download consumes 1 API request.

```bash
curl -fL -OJ \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://cleantempmail.com/api/email/66c123example/attachment/attachment-id"
```

The response body is the file itself. Content-Type, Content-Length, and Content-Disposition are set by the server. curl -OJ saves the safe server-provided filename. Attachment errors are returned as plain text.

### `DELETE /api/email/{id}`: Delete one message

API key · 1 request. Permanently deletes the message identified by id. Fetch the ID from /api/emails first. This action cannot be undone.

```bash
curl -sS -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://cleantempmail.com/api/email/66c123example"
```

### `DELETE /api/emails/clear?email={address}`: Clear an inbox

API key · 1 request. Permanently deletes every stored message for the supplied public mailbox and returns the number deleted. This action cannot be undone.

```bash
curl -sS -X DELETE -G \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "email=alexsmith42@active-domain.example" \
  "https://cleantempmail.com/api/emails/clear"
```

### `GET /api/stats` · `/api/statistics/*`: Stats endpoints

API key · 1 per endpoint. Returns cached public service statistics. Each path is a separate protected request and consumes 1 request. Private-domain mail is excluded from public statistics.

- `/api/stats`: Overall totals: total emails, today, last 24 hours, unique subjects, and active domains.
- `/api/statistics/24h`: Array of hourly UTC buckets with hour and count.
- `/api/statistics/top-subjects`: Top 10 public message subjects with count.
- `/api/statistics/top-domains`: Top 10 public recipient domains with count.
- `/api/statistics/top-senders`: Top 10 senders with count.

### `POST /api/api-key/usage`: Check API key quota

No API key · no quota. Returns status and usage for a purchased, manually created, exhausted, or shared test key. This lookup does not consume quota. Supply the key either in X-API-Key or in a JSON api_key field; the header is recommended.

```bash
curl -sS -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://cleantempmail.com/api/api-key/usage"
```

status is active, exhausted, or inactive. Exhausted purchased keys remain queryable. The full key and Stripe/customer metadata are never returned.

## HTTP errors and recovery

JSON endpoints normally return success: false and an error string. The attachment endpoint returns plain text on failure. Always branch on the HTTP status before reading data.

| HTTP | Meaning | Recommended action |
| --- | --- | --- |
| `400` | Missing or invalid input, such as an absent email parameter or invalid prefix. | Fix the request; do not retry unchanged. |
| `401` | API key is missing, invalid, or no longer active. | Check X-API-Key or purchase/use another active key. |
| `403` | The requested inbox belongs to a private GPTMail domain. | Do not access private GPTMail inboxes through this API. |
| `404` | Message or attachment ID was not found or has expired. | Refresh the inbox list and stop retrying stale IDs. |
| `409` | The explicitly selected generation domain is unavailable. | Fetch /api/domains and deliberately choose an active domain. |
| `429` | Daily or total quota has been exhausted. | Wait for the daily reset or use a newly purchased key; one-time keys cannot be recharged. |
| `503` | Inbox routing is synchronizing or no active domain is available. | Respect Retry-After when present and retry with backoff. |

## API keys

- Shared test key: `ct-test`
- Plans, one-time purchase and key recovery: https://cleantempmail.com/api