๐ฅข 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 setupprovisions 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 setupprovisions D1, Email Routing, zone catch-all rules, and renderswrangler.tomlautomatically. 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.netand 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-SPFandAuthentication-Resultsheaders 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.xmlrequires 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:
- Sender emails
[email protected] - Cloudflare Email Routing delivers to the Worker's
email()handler - PostalMime parses the MIME โ extracts text, HTML, headers, attachments, deliverability status
- Data is stored in D1; the inbox is auto-created if it doesn't exist
- Subscribers listening via SSE get a realtime push
- 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
- Go to the Cloudflare dashboard and log in
- Click your profile icon (top-right) โ My Profile โ API Tokens
- Click Create Token
- Choose Create Custom Token (or use the "Edit zone DNS" template as a starting point)
- Give the token a name like
tempe-mail - 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
- Under Zone Resources, choose All zones (or select the specific zones you'll use)
- Click Continue to summary โ Create Token
- 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
- Go to the Cloudflare dashboard
- Look at the sidebar on the left โ your Account ID is listed right below "Workers & Pages"
- Alternatively: click any domain โ scroll down in the right sidebar โ "Account ID"
- 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:
- Enable R2 in your account: Cloudflare dashboard โ R2 โ Get started (free tier available)
- Create the bucket:
npx wrangler r2 bucket create tempe-mail-attachments - Uncomment the
[[r2_buckets]]block inwrangler.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:
-
Create the D1 database:
npx wrangler d1 create tempe-mail-dbCopy the
database_idfrom the output. -
Apply the schema:
npx wrangler d1 execute tempe-mail-db --remote --file=src/db/schema.sql -
Create the R2 bucket (optional โ for attachment downloads):
npx wrangler r2 bucket create tempe-mail-attachments -
Fill in
wrangler.toml: replace theREPLACED_BY_SETUPplaceholders with your real database ID and routes, and uncomment the[[r2_buckets]]block. -
Enable Email Routing in the dashboard: Cloudflare dashboard โ your domain โ Email โ Email Routing โ enable it, add a catch-all rule pointing to the
tempe-mailworker. -
Deploy:
npx wrangler deploy
Note: Email Worker bindings (
[email]) are always configured via the dashboard/API โ not wrangler.toml. That's whywranglermay warn about the
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:
npm run devโ starts the worker locally athttp://localhost:8787- The D1 schema is applied automatically to the local database on startup (no more
no such tableerrors) - Inbound email is simulated via unit/E2E tests (
tests/email-handler-e2e.test.ts) - The scheduled purge trigger can be fired manually:
curl "http://localhost:8787/cdn-cgi/local/scheduled"
wrangler devis for development only. Production runs on Cloudflare's edge viawrangler 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 typecheckandnpm 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.