# GPTMail API

Base URL: `https://mail.chatgpt.org.uk`

## Quick Start

- X-API-Key: YOUR_KEY is the simplest option. For quick tests, use the daily public key shown above in place of YOUR_KEY.
- Most mailbox endpoints require an email parameter, for example ?email=demo@example.com.
- GPTMail API responses use JSON with success, data, and error fields, plus usage when an API key is used. Cloudflare errors, including rate-limit responses, may return HTML instead. Check the HTTP status and Content-Type before parsing JSON.
- If you already know a currently supported domain on this site, you do not have to call the email generation endpoint first. You can compose prefix@domain locally and call the mailbox APIs directly, which saves one API request.

## Rate limits and retries

- GET and POST /api/generate-email share a limit of 30 requests per 10 seconds per source IP. This applies to both public and personal API keys. Different keys and clients behind the same IP share this limit.
- Exceeding this limit returns HTTP 429 and blocks email generation for 10 seconds. Wait for the Retry-After duration before retrying. If this header is absent, wait at least 10 seconds, then retry with increasing delays. Avoid simultaneous retries from clients sharing an IP.
- This rule does not apply to inbox listing or reading individual emails. API-key daily and total quotas still apply independently. Waiting 10 seconds does not restore an exhausted key quota.

## Core Endpoints

### `POST /api/generate-email`
Generate a temporary inbox. Use GET for the simplest random inbox flow, or POST with prefix and domain when you want explicit control.

### `GET /api/emails?email=...`
Fetch emails for a mailbox.

### `GET /api/email/{id}?email=...`
Fetch a single email, including text, HTML, raw headers, and metadata.

### `DELETE /api/email/{id}?email=...`
Delete one email by ID.

### `DELETE /api/emails/clear?email=...`
Delete all emails in a mailbox.
Each call deletes one batch. While the response has "has_more": true, call it again until it returns false.

### `GET /api/stats`
Read site-wide statistics.

## Example Flow

```bash
# 1) Generate a random temporary email address
curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: YOUR_API_KEY'
# 2) Generate with a fixed prefix (e.g. demo@example.com)
curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"prefix":"demo"}'
# 3) List emails in an inbox
# If you already know a supported domain, skip step 1 and query directly.
curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: YOUR_API_KEY'
# 4) Read a single email — includes plain text, HTML body, and metadata
# Replace EMAIL_ID with an id returned from step 3. Also pass the inbox address as email (for deletes and attachment downloads too): the email is then read directly from its inbox instead of being searched by ID. With an API key the email parameter is optional, but sending it makes the lookup faster.
curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: YOUR_API_KEY'
# 5) Delete a single email by ID
# With an API key the email parameter is optional, but sending it makes the lookup faster.
curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: YOUR_API_KEY'
# 6) Clear an entire inbox — deletes all emails for this address
# Each call deletes one batch. While the response has "has_more": true, call it again until it returns false.
curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: YOUR_API_KEY'
```

## Response Shape

```json
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}
```

## API keys

- Free public test key with a shared daily quota: https://mail.chatgpt.org.uk/api/
- Personal keys with their own daily and total quotas: https://mail.chatgpt.org.uk/account/#api-purchase