Tempe Mail

🥢 TempeMail

Zero-config, multi-domain disposable email on Cloudflare Workers.

TempeMail is a self-hosted disposable email service that runs entirely on the Cloudflare edge — no VPS, no Docker, no SMTP server. One worker handles the web UI, REST API, inbound email delivery, and automatic provisioning.

Deploy in minutes with 3 environment values:

git clone https://github.com/ghufronainun/tempe-mail.git
cd tempe-mail
npm install
cp .env.example .env      # fill 3 values
npm run setup              # provisions everything automatically
npx wrangler deploy        # go live 🚀

Table of Contents

• Why TempeMail?
• Features
• How it works
• Quick Start
• Development
• Project Structure
• API Reference
• Configuration
• Troubleshooting
• Roadmap
• Contributing
• License

Why TempeMail?

TempeMail is a self-hosted disposable email service that runs entirely on the Cloudflare edge — no VPS, no Docker, no SMTP server. One worker handles the web UI, REST API, inbound email delivery, and automatic provisioning.

What sets it apart from other temp-mail projects:

• Multi-domain — serve disposable inboxes across any number of domains from a single worker, without extra config.
• Zero-config setup — npm run setup provisions D1, Email Routing, and zone catch-all rules automatically. Idempotent and re-runnable.
• Deliverability diagnostics — SPF/DKIM/DMARC status for every message, which most temp-mail services don't expose.
• Agent-ready — REST API keys, webhooks, RSS feeds, SSE streams, and a built-in MCP server so AI agents can read inboxes natively.
• Self-hosted — you own the infrastructure and the data, on Cloudflare's free tier.

Features

📬 Core

• Zero-config setup — npm run setup provisions D1, Email Routing, zone catch-all rules, and renders wrangler.toml automatically. Idempotent — safe to re-run anytime.
• Multi-domain — serve disposable inboxes across 1 or N domains from a single worker. DOMAINS=mail.example.com,mail2.example.net and you're done.
• HTML email rendering — full HTML email support, rendered safely in a sandboxed iframe (sandbox=""). Email looks exactly as the sender designed it.
• OTP auto-highlight — verification codes (4–8 digit) are automatically detected and displayed prominently in monospace, so you never hunt for the code.
• Semantic tagging — emails are auto-classified into 🔑 Verification, 🔒 Security, 🧪 Testing, or 📣 Marketing based on subject and sender.
• SPF/DKIM/DMARC viewer — inspect Received-SPF and Authentication-Results headers for every message. Gold for QA and email deliverability testing.

🎛️ UX

• Custom addresses — choose your own local part ([email protected]) or let TempeMail generate a random one.
• Auto-expire — inboxes expire after a configurable TTL (default 24h, range 1h–168h).
• Attachment metadata — file name, type, and size shown as chips.
• Starred messages — pin important emails, persisted in localStorage.
• Filter chips — quickly filter All / Verification / Starred.
• Realtime updates — new messages appear instantly via SSE (Durable Objects).
• Dark mode — beautiful dark-first UI with light toggle.
• i18n — English and Bahasa Indonesia, toggle in one click.
• Fully responsive — mobile-first, breakpoints at 900px and 680px.

🤖 Developer / AI-agent friendly

• REST API — full JSON API for scripts and automation.
• API key auth — Authorization: Bearer tmk_... for scripts/agents (no browser session needed). Keys hashed with SHA-256, revocable.
• Webhooks — POST to any URL when new mail arrives, signed with HMAC-SHA256 (X-TempeMail-Signature).
• MCP server — Model Context Protocol bridge so Claude Code / Cursor / any MCP client can read inboxes as tools (list_inboxes, list_messages, get_message).
• RSS feed per inbox — GET /inboxes/:address/feed.xml requires no auth (the address itself is the secret). Poll it from any script.
• SSE stream per inbox — realtime push to any client.
• Inbox search — GET /inboxes/:address/search?q= searches subject, body, and sender.
• Attachment download — (optional) full attachment bodies stored in R2 and downloadable per message. Without R2 you still get attachment metadata + the message body; only the file download is skipped.
• AGENTS.md — onboarding guide so AI coding agents can work on this repo immediately.

How it works

Sender
  │
  ▼
Cloudflare MX
  │  (Email Routing → Worker)
  ▼
Worker email() handler
  │  PostalMime parses MIME
  │  (text + html + headers + attachments)
  ▼
D1 Database (SQLite)
  ├─ inboxes      (address, expires_at)
  ├─ messages     (body, body_html, spf, dkim, dmarc, ...)
  ├─ attachments  (filename, content_type, size)
  └─ sessions     (browser session ↔ inbox ownership)
  │
  ┌────┴────┐
  ▼         ▼
REST API   Web UI (static assets)
  │         ├─ index.html
  ├─ /api/session          └─ app.js (vanilla JS, no framework)
  ├─ /api/inboxes
  ├─ /api/inboxes/:addr/messages
  ├─ /api/inboxes/:addr/feed.xml   (RSS)
  └─ /api/inboxes/:addr/events     (SSE)

The flow:

1. Sender emails [email protected]
2. Cloudflare Email Routing delivers to the Worker's email() handler
3. PostalMime parses the MIME — extracts text, HTML, headers, attachments, deliverability status
4. Data is stored in D1; the inbox is auto-created if it doesn't exist
5. Subscribers listening via SSE get a realtime push
6. Web UI polls or streams and renders everything with OTP highlight + semantic tags

Tech stack

Quick Start

Prerequisites

• A Cloudflare account (free tier is enough)
• At least one domain managed by Cloudflare DNS
• Node.js 18+ and npm

1. Clone & install

git clone https://github.com/ghufronainun/tempe-mail.git
cd tempe-mail
npm install

2. Get your Cloudflare credentials

You need two things from Cloudflare: an API token and your account ID.

Create an API token

1. Go to the Cloudflare dashboard and log in
2. Click your profile icon (top-right) → My Profile → API Tokens
3. Click Create Token
4. Choose Create Custom Token (or use the "Edit zone DNS" template as a starting point)
5. Give the token a name like tempe-mail
6. Add these permissions (all needed for one-command provisioning):
   • Account → Workers Scripts → Edit
   • Account → Workers D1 → Edit
   • Account → Workers R2 Storage → Edit
   • Account → Email Routing Addresses → Edit
   • Account → Email Routing Rules → Edit
   • Zone → Zone → Read (for all zones that host your mail domains)
   • Zone → DNS → Edit (optional, for automatic DNS records)
   • Zone → Email Routing → Edit
7. Under Zone Resources, choose All zones (or select the specific zones you'll use)
8. Click Continue to summary → Create Token
9. Copy the token immediately — it's shown only once. It looks like xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Treat this token like a password. Anyone with it can modify your Cloudflare resources. It is stored in .env (gitignored) — never commit it.

Find your Account ID

1. Go to the Cloudflare dashboard
2. Look at the sidebar on the left — your Account ID is listed right below "Workers & Pages"
3. Alternatively: click any domain → scroll down in the right sidebar → "Account ID"
4. It's a 32-character hex string like a1b2c3d4e5f60718293a4b5c6d7e8f90

3. Configure

cp .env.example .env

Edit .env — only 3 values are required:

CLOUDFLARE_API_TOKEN=your_cf_api_token     # Workers + D1 + Email Routing + Zone permissions
CLOUDFLARE_ACCOUNT_ID=your_account_id      # dashboard → Workers & Pages → account ID
DOMAINS=mail.example.com                   # one or more, comma-separated
WEB_HOST=temp.example.com                  # subdomain for the web UI

Multi-domain? Just add more: DOMAINS=mail.example.com,mail2.example.net,mail3.example.org

4. Setup & deploy

npm run setup        # creates D1, applies schema, enables Email Routing,
                     # sets catch-all → worker for every domain, renders wrangler.toml
npx wrangler deploy  # pushes the worker + static assets to the edge

Open https://temp.example.com and start receiving email. 🎉

Expected setup output:

📦 Setting up D1 database...
   Created D1 database: 12345678-...
📋 Applying schema...
   Schema applied.
🌐 Discovering zone IDs...
   mail.example.com → zone abcdef...
📧 Provisioning Email Routing...
   mail.example.com: catch-all → worker:tempe-mail (enabled)
📝 Rendering wrangler.toml...
   wrangler.toml rendered.

✅ Setup complete!
   1. Review wrangler.toml
   2. Run: npx wrangler deploy
   3. Open: https://temp.example.com

Optional: enable R2 attachment downloads

R2 is optional — without it TempeMail works fully (metadata + body), only file downloads are skipped. To enable:

1. Enable R2 in your account: Cloudflare dashboard → R2 → Get started (free tier available)
2. Create the bucket:

   npx wrangler r2 bucket create tempe-mail-attachments
   

3. Uncomment the [[r2_buckets]] block in wrangler.toml, fill in your bucket name, then re-deploy:

   npx wrangler deploy
   

Optional: manual setup (if the script hits permission limits)

If your API token lacks D1 or Email Routing permissions, npm run setup may skip those steps. You can do them manually:

1. Create the D1 database:

   npx wrangler d1 create tempe-mail-db
   

   Copy the database_id from the output.

2. Apply the schema:

   npx wrangler d1 execute tempe-mail-db --remote --file=src/db/schema.sql
   

3. Create the R2 bucket (optional — for attachment downloads):

   npx wrangler r2 bucket create tempe-mail-attachments
   

4. Fill in wrangler.toml: replace the REPLACED_BY_SETUP placeholders with your real database ID and routes, and uncomment the [[r2_buckets]] block.

5. Enable Email Routing in the dashboard: Cloudflare dashboard → your domain → Email → Email Routing → enable it, add a catch-all rule pointing to the tempe-mail worker.

6. Deploy:

   npx wrangler deploy
   

Note: Email Worker bindings ([email]) are always configured via the dashboard/API — not wrangler.toml. That's why wrangler may warn about the email field; it's harmless.

Development

npm run dev           # applies schema to local D1, then starts wrangler dev (port 8787)
npm test              # run all 77 tests (Vitest)
npm run typecheck     # strict TypeScript check

Local dev guide:

1. npm run dev — starts the worker locally at http://localhost:8787
2. The D1 schema is applied automatically to the local database on startup (no more no such table errors)
3. Inbound email is simulated via unit/E2E tests (tests/email-handler-e2e.test.ts)
4. The scheduled purge trigger can be fired manually: curl "http://localhost:8787/cdn-cgi/local/scheduled"

wrangler dev is for development only. Production runs on Cloudflare's edge via wrangler deploy — your machine/VPS is completely uninvolved.

Project Structure

tempe-mail/
├── src/
│   ├── index.ts                 # Worker entry: fetch() + email() + scheduled purge
│   ├── env.ts                   # Environment bindings interface
│   ├── email/
│   │   ├── ingest.ts            # MIME parsing (PostalMime) → text/html/headers/attachments
│   │   └── headers.ts           # SPF/DKIM/DMARC extraction from raw headers
│   ├── api/
│   │   ├── routes.ts            # Hono REST API (session, inboxes, messages)
│   │   ├── rss.ts               # Per-inbox RSS 2.0 feeds
│   │   ├── tagging.ts           # Semantic classifier (content rules)
│   │   └── realtime.ts          # SSE endpoint → Durable Object
│   ├── cf/
│   │   ├── zones-loader.ts      # CF_ZONE_MAP env → domain→zone map
│   │   └── routing.ts           # Email Routing provisioning (setup-time)
│   ├── db/
│   │   ├── schema.sql           # D1 schema (inboxes, messages, attachments, sessions)
│   │   └── realtime-room.ts     # Durable Object: SSE room per inbox
│   └── web/                     # Frontend (vanilla, dark theme)
│       ├── index.html
│       ├── app.js               # Rendering, polling/SSE, OTP, tags, i18n
│       ├── styles.css           # Responsive, dark/light, 3 breakpoints
│       └── i18n/{en,id}.js      # String dictionaries
├── scripts/
│   ├── setup.mjs                # Zero-config provisioning script
│   └── dev.mjs                  # Dev helper (auto-schema + wrangler dev)
├── tests/                       # Vitest: 5 files, 77 tests
├── .github/workflows/ci.yml     # CI: typecheck + tests on push/PR
├── .env.example                 # Environment template
├── wrangler.toml                # Generated by setup (placeholders committed)
├── README.md
├── AGENTS.md                    # AI-agent onboarding guide
├── API.md                       # Full API reference
└── LICENSE                      # MIT

API Reference

Authentication

Browser sessions via x-session-id header. Create one:

POST /api/session
→ { "sessionId": "uuid-v4" }

All inbox/message endpoints require the header. Inbox ownership is enforced — you can only read messages from inboxes your session owns.

Endpoints

Example: create inbox

curl -X POST https://temp.example.com/api/inboxes \
  -H "x-session-id: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{"localPart": "myalias", "ttlHours": 48}'

{
  "address": "[email protected]",
  "domain": "mail.example.com",
  "ttlHours": 48
}

Full reference: API.md · Live docs: /docs

Configuration

All values are read at setup time. Secrets stay in .env (gitignored) — never commit them.

Troubleshooting

Roadmap

See AGENTS.md and the plan document for details.

✅ Phase 2 — done

• REST API key authentication (no browser session needed)
• Webhooks (POST to a URL on new mail, HMAC-signed)
• MCP server (Model Context Protocol) for AI agents
• Full attachment download (R2 storage)
• Inbox search

🔜 Planned

• Frontend UI for API keys, webhooks, and search (backends are API-ready)
• Rate limiting per key
• Multiple webhook events (message deleted, inbox expired)

Contributing

Contributions are welcome! Open an issue or PR.

• Start with CONTRIBUTING.md — setup, conventions, quality gate
• All code must pass: npm run typecheck and npm test
• Follow the Code of Conduct
• Found a vulnerability? See SECURITY.md — please report privately
• Use the issue/PR templates in .github/

License

MIT © 2026 masantoid, TempeMail contributors.

Derived from hirotomasato/tempik. TempeMail has been rewritten from scratch with multi-domain support, deliverability diagnostics, zero-config provisioning, and an original UI. This project is distributed under the MIT License — see the LICENSE file for the full text.