# Temp Mail API
> Disposable / temporary email as an API — no key, no signup. Spin up a throwaway mailbox in one call (you get back the address plus a token), then receive real inbound email and read it: list the inbox, open any message with its full HTML and plain-text body and attachments, mark messages seen, delete a single message, or delete the whole mailbox when done. List the available mailbox domains and look up account details (quota, usage). Perfect for sign-up flows, OTP / verification-code capture, QA and end-to-end test automation, and throwaway registrations. Inbox endpoints use a per-mailbox token returned by /v1/account/new (pass it as ?token= or an Authorization: Bearer header). Every call is live (no cache). 9 endpoints, backed by the public mail.tm service. Mailboxes are ephemeral. No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tempmail-api/..."
```

## Pricing
- **Free** (Free) — 2,400 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 48,000 calls/Mo, 8 req/s
- **Pro** ($27/Mo) — 240,000 calls/Mo, 20 req/s
- **Mega** ($61/Mo) — 1,180,000 calls/Mo, 50 req/s

## Endpoints

### Mailbox

#### `GET /v1/account` — Account details

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/account"
```

#### `GET /v1/account/delete` — Delete mailbox

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/account/delete"
```

#### `GET /v1/account/new` — Create disposable mailbox

**Parameters:**
- `username` (query, optional, string) — Custom local part (default: random)
- `domain` (query, optional, string) — Domain (default: first available)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/account/new"
```

**Response:**
```json
{
    "data": {
        "id": "6a1f0a74da099a12b904068e",
        "note": "Use this token (as ?token= or Authorization: Bearer) to read the inbox. The mailbox is disposable and may be purged by mail.tm.",
        "used": 0,
        "quota": 40000000,
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3ODA0MTkxODgsInJvbGVzIjpbIlJPTEVfVVNFUiJdLCJhZGRyZXNzIjoib2Ewc280cm1od3ZyQHdzaHUubmV0IiwiaWQiOiI2YTFmMGE3NGRhMDk5YTEyYjkwNDA2OGUiLCJtZXJjdXJlIjp7InN1YnNjcmliZSI6WyIvYWNjb3VudHMvNmExZjBhNzRkYTA5OWExMmI5MDQwNjhlIl19fQ.4Nq9EMw5dT75tJJu-vZxga4lrk3Adc62mHnOPt713uf4eRP612-QmWR_6Xtx9xx47prMzO4Ot-sETfwl3MwQKw",
        "address": "oa0so4rmhwvr@wshu.net",
        "password": "Pwx0kg7yt05wwqb7",
        "createdAt": "2026-06-02T16:53:08+00:00"
    },
    "meta": {
        "timestamp": "2026-06-02T16:53:08.948Z",
        "request_id": "0fe6ca5f-34af-45ed-b2db-57ba0829f344"
    },
    "status": "ok",
    "message": "Create disposable mailbox",
    "success": true
}
```

#### `GET /v1/domains` — Available mailbox domains

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/domains"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "domains": [
            {
                "id": "69fbf6b9ab3b957d116c6be8",
                "domain": "wshu.net",
                "isActive": true,
                "createdAt": "2026-05-07T00:00:00+00:00"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-02T16:53:09.048Z",
        "request_id": "90c4748a-a12c-40df-ae04-0637a424406f"
    },
    "status": "ok",
    "message": "Available mailbox domains",
    "success": true
}
```

### Messages

#### `GET /v1/message` — Read one message

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new
- `id` (query, required, string) — Message id

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/message"
```

#### `GET /v1/message/delete` — Delete one message

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new
- `id` (query, required, string) — Message id

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/message/delete"
```

#### `GET /v1/message/seen` — Mark message seen

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new
- `id` (query, required, string) — Message id

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/message/seen"
```

#### `GET /v1/messages` — List inbox messages

**Parameters:**
- `token` (query, required, string) — Mailbox JWT from /v1/account/new
- `page` (query, optional, string) — Page

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/messages"
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tempmail-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key. Inbox endpoints need a per-mailbox token from /v1/account/new.",
        "name": "Temp Mail API",
        "note": "Create a throwaway mailbox, receive real inbound email, read/delete messages. Live, no cache. Token is a JWT — pass as ?token= or Authorization: Bearer. Mailboxes are ephemeral and may be purged upstream.",
        "source": "mail.tm public REST (disposable email) — no key",
        "endpoints": 9
    },
    "meta": {
        "timestamp": "2026-06-02T16:53:09.156Z",
        "request_id": "3fe60712-ef00-458f-b8d8-ff83fe8dc39b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/tempmail-api
OpenAPI spec: https://www.oanor.com/api/tempmail-api/openapi.json