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.
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
/api/inboxessession or BearerCreate 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 }
| Field | Type | Default | Description |
|---|---|---|---|
localPart | string | random | Mailbox name, following any configured routing prefix. Taken names return HTTP 409. Use the full address returned by the API. |
domain | string | random | One of the configured mail domains. |
ttlHours | int | 24 | Expiry, clamped to 1–168 (7 days). |
/api/inboxessession or BearerList inboxes owned by the principal (non-expired).
→ [ { "address": "myalias@domain.com", "created_at": "...", "expires_at": "..." } ]
/api/inboxes/:addresssession or BearerUnlink an inbox from the principal. Returns { "deleted": true }.
Messages
/api/inboxes/:address/messagessession or BearerList 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": "..."
}]
/api/messages/:idsession or BearerFetch a single message by id (ownership-checked).
Search
/api/inboxes/:address/search?q=...session or BearerSearch messages by subject, body, or sender. Query must be at least 2 characters. Returns up to 50 results.
curl -H "x-session-id: <sessionId>" \
"https://YOUR_HOST/api/inboxes/myalias@domain.com/search?q=verify"
# → [ { "id":"...", "subject":"...", "from_address":"...", "received_at":"..." } ]
Webhooks
Subscribe an inbox to receive new_message events. Deliveries are HMAC-SHA256 signed with your secret.
/api/inboxes/:address/webhookssession or BearerCreate 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" }
/api/inboxes/:address/webhookssession or BearerList webhook subscriptions for an inbox.
/api/inboxes/:address/webhooks/:idsession or BearerRemove 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": "..."
}
}
secret, compare to v1=<hex>. OTP-looking codes are redacted from body_preview before external delivery.Realtime (SSE)
/api/inboxes/:address/eventssession or BearerServer-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
/api/messages/:id/attachments/:filenamesession or BearerDownload an attachment. Returns the file if stored in R2; 410 with metadata if R2 is not configured (metadata-only).
API Keys
/api/keysbrowser session onlyCreate an API key. Prefix tmk_, shown once, stored hashed.
/api/keysbrowser session onlyList API keys (name, created, last used, revoked).
/api/keys/:idbrowser session onlyRevoke an API key.
RSS
/:address/feed.xmlpublicPublic 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
TEMPEMAIL_API_KEY is required — it exits immediately without one.