Skip to content

Documentation

Self-hosted disposable email on Cloudflare Workers. Create inboxes, receive mail, read messages, subscribe to webhooks, and integrate agents via API keys or MCP.

REST API Webhooks MCP SSE Realtime

Authentication

Two ways to authenticate. Most browser flows use a session; programmatic use uses an API key.

Browser session

Create a session, then send it as x-session-id on subsequent requests.

# Create session
curl -X POST https://YOUR_HOST/api/session
# → { "sessionId": "550e8400-e29b-41d4-a716-446655440000" }

# Use it
curl -H "x-session-id: 550e8400-e29b-41d4-a716-446655440000" \
  https://YOUR_HOST/api/inboxes

API key (Bearer)

Create a key from a browser session, then authenticate with Authorization: Bearer <key>. Keys are stored SHA-256 hashed and can be revoked.

# Create a key (needs a browser session)
curl -X POST -H "x-session-id: <sessionId>" \
  -H "x-key-name: ci-bot" \
  https://YOUR_HOST/api/keys
# → { "id": 1, "key": "tmk_2f3a...", "name": "ci-bot" }

# Use it
curl -H "Authorization: Bearer <key>" \
  https://YOUR_HOST/api/inboxes

Inboxes

POST/api/inboxessession or Bearer

Create a new inbox. Random address by default, or specify your own.

curl -X POST -H "x-session-id: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"myalias","ttlHours":48}' \
  https://YOUR_HOST/api/inboxes
# → { "address": "myalias@domain.com", "domain": "domain.com", "ttlHours": 48 }
FieldTypeDefaultDescription
localPartstringrandomMailbox name, following any configured routing prefix. Taken names return HTTP 409. Use the full address returned by the API.
domainstringrandomOne of the configured mail domains.
ttlHoursint24Expiry, clamped to 1–168 (7 days).
GET/api/inboxessession or Bearer

List inboxes owned by the principal (non-expired).

→ [ { "address": "myalias@domain.com", "created_at": "...", "expires_at": "..." } ]
DELETE/api/inboxes/:addresssession or Bearer

Unlink an inbox from the principal. Returns { "deleted": true }.

Messages

GET/api/inboxes/:address/messagessession or Bearer

List messages in an inbox. Each includes deliverability (SPF/DKIM/DMARC), a semantic tag, and attachments.

→ [{
  "id": "msg_...",
  "from_address": "noreply@github.com",
  "from_name": "GitHub",
  "subject": "[GitHub] Verify your email",
  "body": "Plain text...",
  "body_html": "<html>...",
  "spf": "pass", "dkim": "pass", "dmarc": "pass",
  "tag": "verification", "tag_label": "Verification",
  "attachments": [ { "filename":"file.pdf", "content_type":"application/pdf", "size":1234 } ],
  "received_at": "..."
}]
GET/api/messages/:idsession or Bearer

Fetch a single message by id (ownership-checked).

Webhooks

Subscribe an inbox to receive new_message events. Deliveries are HMAC-SHA256 signed with your secret.

POST/api/inboxes/:address/webhookssession or Bearer

Create a webhook subscription.

curl -X POST -H "x-session-id: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myapp.com/hook","secret":"s3cret"}' \
  https://YOUR_HOST/api/inboxes/myalias@domain.com/webhooks
# → { "id": 1, "inbox_address":"...", "url":"...", "events":"new_message" }
GET/api/inboxes/:address/webhookssession or Bearer

List webhook subscriptions for an inbox.

DELETE/api/inboxes/:address/webhooks/:idsession or Bearer

Remove a webhook subscription.

Webhook payload

POST {your_url}
X-TempeMail-Signature: v1=<hmac-sha256-hex>

{
  "event": "new_message",
  "inbox_address": "myalias@domain.com",
  "message": {
    "id": "msg_...",
    "from_address": "...",
    "from_name": "...",
    "subject": "...",
    "body_preview": "First 200 chars (OTP codes redacted)",
    "received_at": "..."
  }
}
Verify signature: HMAC-SHA256 of the raw request body using your webhook secret, compare to v1=<hex>. OTP-looking codes are redacted from body_preview before external delivery.

Realtime (SSE)

GET/api/inboxes/:address/eventssession or Bearer

Server-Sent Events stream. A new_message event fires when mail arrives. Ownership required.

curl -N -H "x-session-id: <sessionId>" \
  https://YOUR_HOST/api/inboxes/myalias@domain.com/events

data: {"type":"connected"}
data: {"type":"new_message","message":{"id":"...","subject":"..."}}

Attachments

GET/api/messages/:id/attachments/:filenamesession or Bearer

Download an attachment. Returns the file if stored in R2; 410 with metadata if R2 is not configured (metadata-only).

API Keys

POST/api/keysbrowser session only

Create an API key. Prefix tmk_, shown once, stored hashed.

GET/api/keysbrowser session only

List API keys (name, created, last used, revoked).

DELETE/api/keys/:idbrowser session only

Revoke an API key.

RSS

GET/:address/feed.xmlpublic

Public RSS 2.0 feed for an address. Mounted at root (not under /api).

MCP Server

Run a local MCP server so AI agents (Claude Code, Cursor) can read your inboxes over the Model Context Protocol. It bridges MCP tool calls to the REST API using a Bearer key. Tools: list_inboxes, list_messages, get_message.

1. Create an API key

curl -X POST -H "x-session-id: <sessionId>" \
  -H "x-key-name: my-agent" \
  https://YOUR_HOST/api/keys
# → { "id": 1, "key": "tmk_..." }

2. Run the server

The entry point is TypeScript, so run it with tsx (bundled as a dependency) — not plain node.

# From the project root
TEMPEMAIL_BASE_URL=https://YOUR_HOST \
TEMPEMAIL_API_KEY=tmk_... \
npx tsx src/api/mcp.ts

# or via the npm script (reads env from your shell)
npm run mcp

3. Register with Claude Code

claude mcp add tempe-mail -- \
  env TEMPEMAIL_BASE_URL=https://YOUR_HOST TEMPEMAIL_API_KEY=tmk_... \
  npx tsx /absolute/path/to/tempe-mail/src/api/mcp.ts
Note: the server speaks stdio JSON-RPC 2.0 and is read-only. TEMPEMAIL_API_KEY is required — it exits immediately without one.