TempMail OTP Server

Receive-only temp email server with automatic OTP extraction for security research, QA automation, and disposable identity workflows.

Features

• SMTP catch-all — accepts all inbound email on your domain (port 25, no auth)
• Real-time inbox — SSE stream pushes new emails instantly to the browser
• OTP extraction — automatic detection of verification codes (4–8 digit, alphanumeric)
• Link extraction — parse all URLs from plain-text and HTML email bodies
• REST API — authenticated endpoints for email generation, reading, OTP, and link extraction
• MCP integration — stdio-based Model Context Protocol server for AI agents (Hermes, Claude, etc.)
• Docker — multi-stage build, SQLite persistence, health check included
• Dark/light mode — built with Tailwind CSS + shadcn/ui
• DNS verification — built-in /api/dns-check endpoint validates MX, SPF, DMARC records
• Multi-key support — manage API keys via the web UI or /api/keys endpoint

Prerequisites

• Node.js 20+ (with tsx for MCP; npm for package management)
• Domain name — configured with MX, SPF, and DMARC records
• Port 25 access — required for SMTP receiving; unavailable on most home ISPs. Use a VPS (Oracle Cloud Free Tier, AWS EC2, DigitalOcean) or port forwarding if supported

Quick Start

1. Clone and install

git clone <repo-url> website-email
cd website-email
npm install

2. Configure environment

cp .env.example .env

Edit .env with your domain and a strong API key:

DOMAIN=mail.yourdomain.com
API_KEY=your-generated-api-key

Generate a secure API key:

openssl rand -hex 32

3. Set up DNS records

Configure MX, SPF, and DMARC records for your domain. See the complete guide:

→ docs/dns-setup.md

Quick verification after DNS propagates:

dig MX yourdomain.com +short
dig TXT yourdomain.com +short | grep spf
dig TXT _dmarc.yourdomain.com +short

4. Start the servers

Terminal 1 — Next.js web UI + API:

npm run dev

Terminal 2 — SMTP server (receives mail):

npx tsx src/infrastructure/smtp/start.ts

5. Open the app

http://localhost:3000

Generate a temp email address, send a test email to it, and watch it appear in real-time.

Docker Deployment

1. Configure .env

Same as Quick Start — fill in DOMAIN and API_KEY.

2. Build and start

docker compose up -d

3. Verify

curl http://localhost:3000/api/config
# {"success":true,"data":{"domain":"mail.yourdomain.com"}}

Note: Docker Compose exposes port 3000 only (web UI + API). Run the SMTP server directly on the host for port 25:

npx tsx src/infrastructure/smtp/start.ts

For production, use a reverse proxy (nginx/Caddy) for TLS termination and run SMTP via a process manager (systemd, pm2).

Environment Variables

Variable	Required	Default	Description
DOMAIN	Yes	—	Your domain for receiving email (e.g. mail.example.com)
API_KEY	Yes	—	Secret key for API and MCP authentication
SMTP_PORT	No	25	Port for inbound SMTP
SMTP_HOST	No	0.0.0.0	Bind address for SMTP server
DB_PATH	No	./data/emails.db	SQLite database file path
NEXT_PUBLIC_APP_URL	No	http://localhost:3000	Public URL of the application

REST API

All endpoints (except /api/config and /api/dns-check) require an x-api-key header. Response format: { "success": true, "data": ... } or { "success": false, "error": "..." }.

Email Addresses

Method	Endpoint	Description
GET	/api/addresses	List all addresses
POST	/api/addresses	Generate new address (optional body: { "address": "custom@domain" })
DELETE	/api/addresses/:id	Delete an address and its emails

Emails

Method	Endpoint	Description
POST	/api/emails/generate	Generate address (shorthand)
GET	/api/emails/:address	List emails for an address
GET	/api/emails/:address/:id	Read a specific email
DELETE	/api/emails/:address/:id	Delete a specific email
POST	/api/emails/:address/:id/otp	Extract OTP from email
GET	/api/emails/:address/:id/links	Extract links from email
GET	/api/emails/:address/stream	SSE stream for real-time email events

Misc

Method	Endpoint	Description
GET	/api/config	Get server domain (no auth)
GET	/api/dns-check	Verify DNS records (MX, SPF, DMARC)
GET	/api/keys	List API keys
POST	/api/keys	Create new API key

Example: Full workflow

KEY="your-api-key"
DOMAIN="mail.example.com"

# Generate an address
curl -sH "x-api-key: $KEY" -X POST http://localhost:3000/api/emails/generate | jq

# List emails
curl -sH "x-api-key: $KEY" "http://localhost:3000/api/emails/temp-abc123@$DOMAIN" | jq

# Read email and extract OTP
curl -sH "x-api-key: $KEY" -X POST \
  "http://localhost:3000/api/emails/temp-abc123@$DOMAIN/eml_xxx/otp" | jq

MCP Integration

The MCP server exposes 5 tools for AI agents via stdio transport:

Tool	Description
temp_email_generate	Generate a new temporary email address
temp_email_list	List emails for an address
temp_email_read	Read a specific email by ID
temp_email_extract_otp	Extract OTP/verification code from an email
temp_email_extract_links	Extract all links from an email

Configuration and workflow documentation:

→ docs/hermes-integration.md — Hermes MCP configuration → docs/chrome-devtools-mcp.md — Browser automation with Chrome DevTools MCP → docs/workflow-examples.md — Copy-paste ready prompts

Quick test:

DOMAIN=mail.example.com API_KEY=your-key npx tsx src/infrastructure/mcp/start.ts

Architecture

┌─────────────────────────────────────────────┐
│                 Internet                     │
│  (inbound SMTP on port 25 from any server)  │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  SMTP Server (smtp-server, port 25)          │
│  - Accepts all mail for configured DOMAIN    │
│  - Parses MIME with mailparser               │
│  - Extracts OTP codes automatically          │
│  - Stores to SQLite                          │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  SQLite (better-sqlite3, WAL mode)           │
│  - addresses, emails, api_keys tables         │
│  - Event emitter for SSE notifications        │
└────────┬──────────────────┬──────────────────┘
         │                  │
         ▼                  ▼
┌─────────────────┐  ┌─────────────────────────┐
│  Next.js App     │  │  MCP Server (stdio)      │
│  - Web UI        │  │  - 5 tools for AI agents │
│  - REST API      │  │  - Direct DB access      │
│  - SSE stream    │  │                          │
└─────────────────┘  └─────────────────────────┘

Stack: Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui + better-sqlite3 + smtp-server + mailparser

Additional Documentation

• docs/dns-setup.md — DNS record configuration (MX, SPF, DMARC)
• docs/deployment.md — Production deployment (Oracle Cloud, SSL)
• docs/troubleshooting.md — Common issues and solutions
• docs/hermes-integration.md — Hermes AI agent MCP configuration
• docs/chrome-devtools-mcp.md — Browser automation workflows
• docs/workflow-examples.md — End-to-end automation examples

License

MIT