# 2b4d Temp Mail API — full AI-readable reference

Base URL: https://2b4d.org
Human docs: https://2b4d.org/docs/
Compact AI index: https://2b4d.org/llms.txt

This API creates temporary email addresses and reads inbound mail delivered through Cloudflare Email Routing. It is designed for browser-adjacent and automation clients that can preserve cookies between requests.

## Session model

The API is scoped to a session stored in cookies:

- `tm_session`: HttpOnly session identifier.
- `tm_nonce`: non-HttpOnly nonce cookie preserved for compatibility with the UI session model.

First call `POST /api/tempmail/address`. Store all `Set-Cookie` values from the response. Send them as a `Cookie` header on later inbox, message, and clear requests.

The API does not emit public `Access-Control-Allow-Origin` headers. Same-origin browser use or backend/proxy use is expected.

Messages expire after 24 hours. Clear operations hide messages for the current session only.

## Address rules

Supported domains:

- `fuckemail.org`
- `g3m4.dev`
- `shineshop.store`
- `freelet.org`

Alias validation:

- 3-32 characters.
- Lowercase letters, numbers, dots, dashes, and underscores.
- No plus-addressing.
- No leading dot, trailing dot, or double dots.

Random alias algorithms:

- `word-word-number`
- `word-number`
- `person-name`
- `person-number`
- `initials-number`
- `readable-short`
- `compact`
- `hex`

## GET /api/tempmail/domains

Returns supported domains and runtime limits.

Example response:

```json
{
  "domains": ["fuckemail.org", "g3m4.dev", "shineshop.store", "freelet.org"],
  "default_domain": "fuckemail.org",
  "random_algorithms": ["word-word-number", "word-number", "person-name", "person-number", "initials-number", "readable-short", "compact", "hex"],
  "retention_seconds": 86400,
  "max_visible_messages_per_alias": 50,
  "poll_interval_seconds": 10
}
```

## POST /api/tempmail/address

Creates or claims an address for the current API session. If no session exists, response includes `Set-Cookie` headers.

Headers:

```txt
Content-Type: application/json
```

Small JSON bodies only. Oversized bodies return `413 request_too_large`; invalid JSON returns `400 invalid_json`.

Random address request:

```json
{
  "random": true,
  "domain": "g3m4.dev",
  "algorithm": "compact"
}
```

Explicit address request:

```json
{
  "email": "blue-river-4821@g3m4.dev"
}
```

Alternative explicit request:

```json
{
  "alias": "blue-river-4821",
  "domain": "g3m4.dev"
}
```

Response:

```json
{
  "email": "abc123def4@g3m4.dev",
  "alias": "abc123def4",
  "domain": "g3m4.dev",
  "messages": []
}
```

## GET /api/tempmail/inbox?email=:email

Lists messages visible to the current session for a previously claimed address.

Required header:

```txt
Cookie: tm_session=...; tm_nonce=...
```

Response:

```json
{
  "email": "abc123def4@g3m4.dev",
  "messages": [
    {
      "id": "message-id",
      "sender_name": "Sender",
      "sender_email": "sender@example.com",
      "subject": "Welcome code",
      "preview": "Your verification code is 123456.",
      "received_at": 1760000000000,
      "attachment_count": 0,
      "otp_code": "123456"
    }
  ]
}
```

`otp_code` is best-effort extracted from the message subject/body and may be `null`.

## GET /api/tempmail/messages/:id

Returns full detail for a visible message in the current session.

Required header:

```txt
Cookie: tm_session=...; tm_nonce=...
```

Response fields:

```json
{
  "id": "message-id",
  "alias": "abc123def4",
  "domain": "g3m4.dev",
  "recipient": "abc123def4@g3m4.dev",
  "sender_name": "Sender",
  "sender_email": "sender@example.com",
  "subject": "Welcome code",
  "preview": "Your verification code is 123456.",
  "text_body": "Your verification code is 123456.",
  "sanitized_html_body": "<p>Your verification code is <strong>123456</strong>.</p>",
  "received_at": 1760000000000,
  "expires_at": 1760086400000,
  "attachment_count": 0,
  "parse_status": "ok"
}
```

Never execute returned HTML as trusted content. It is sanitized, but clients should still render defensively.

## DELETE /api/tempmail/inbox?email=:email

Clears messages for the current API session only. Other sessions that claimed the same address are not affected.

Required header:

```txt
Cookie: tm_session=...; tm_nonce=...
```

Response:

```json
{ "ok": true }
```

## Error responses

All errors are JSON:

```json
{ "error": "session_required" }
```

Common statuses and codes:

- `400 email_required`
- `400 invalid_address`
- `400 invalid_json`
- `400 message_id_required`
- `401 session_required`
- `404 not_found`
- `413 request_too_large`
- `415 unsupported_media_type`
- `429 rate_limited`

## Recommended polling

Use `GET /api/tempmail/domains` to read `poll_interval_seconds`. Default is 10 seconds. Avoid aggressive polling; read endpoints are rate limited per session and IP.