TempMail OTP — Self-Hosted Temporary Email Generator

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

Related MCP server: useblip/email

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

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

Emails

Misc

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:

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