Build a Secure Temporary Email Service with Cloudflare Workers and D1 Database

Ever needed a temporary email address to avoid spam or protect your privacy? Discover how to build your own secure, privacy-focused email solution using Cloudflare’s serverless platform.

What Is a Temporary Email Service?

A temporary email service provides disposable email addresses you can use for website registrations, verifications, or any situation where you don’t want to share your primary email. These addresses automatically expire after use, protecting your inbox from spam and maintaining your privacy.

Project Showcase

Experience it live:
🔗 https://mail.dinging.top/
🔑 Password: admin

Modern Glassmorphism Interface

Homepage Display
Clean design with glass-like transparency effects and smooth gradients

Password Protection

Login/Password Protection
Secure authentication protects your temporary emails

Email Content Viewing

Email Content Display
Full HTML rendering preserves email formatting

Verification Code Copying

Easy Verification Code Copying
Smart code detection with one-click copying

Core Functionality

🎨 Modern User Interface

  • Glassmorphism design: Contemporary translucent elements with background blur
  • Responsive layout: Seamless experience on mobile and desktop
  • Smooth animations: Interactive feedback for user actions
  • Light theme: Clean, eye-friendly interface

📧 Email Management

  • Random generation: Create unique email addresses on demand
  • History tracking: Automatically save previously used addresses
  • Bulk management: Delete individual or multiple addresses
  • Quick switching: Easily toggle between different email accounts

💌 Email Processing

  • Real-time receiving: Instant email delivery to your dashboard
  • Auto-refresh: Checks for new emails every 8 seconds
  • Smart detection: Automatically highlights verification codes
  • Content rendering: Displays both HTML and plain text emails
  • One-click actions: Copy codes or entire messages instantly

⚙️ Technical Advantages

  • Global acceleration: Leverages Cloudflare’s 200+ data centers
  • Persistent storage: D1 database ensures data reliability
  • Secure authentication: JWT token protection for all endpoints
  • RESTful API: Full integration capabilities for developers

Step-by-Step Deployment Guide

1. Create D1 Database

# Install Wrangler CLI
npm install -g wrangler

# Log in to Cloudflare
wrangler login

# Create D1 database
wrangler d1 create temp-mail-db

2. Configure Project Settings

Create a wrangler.toml file with these contents:

main = "src/index.js"

[[d1_databases]]
binding = "TEMP_MAIL_DB"
database_name = "temp-mail-db"
database_id = "YOUR_DATABASE_ID"

[vars]
MAIL_DOMAIN = "yourdomain.com, backupdomain.cn"  # Separate multiple domains with commas

3. Deploy to Cloudflare

# Set security secrets
wrangler secret put ADMIN_PASSWORD
wrangler secret put JWT_TOKEN

# Test locally
wrangler dev

# Deploy to production
wrangler deploy

4. Initialize Database Structure

wrangler d1 execute TEMP_MAIL_DB --file=./d1-init-basic.sql

5. Configure Email Routing

  1. Go to Cloudflare dashboard > Email Routing
  2. Add catch-all rule
  3. Set destination to Worker: temp-mail-worker
  4. Verify MX records point to Cloudflare’s mail servers

Optional: Custom Domain Setup

Add your domain in Workers > Settings > Triggers, or use Cloudflare’s free *.workers.dev subdomain.

Environment Variables Configuration

Variable Purpose Required
TEMP_MAIL_DB D1 database binding Yes
MAIL_DOMAIN Domain(s) for email addresses Yes
ADMIN_PASSWORD Access password for dashboard Yes
JWT_TOKEN Secret for authentication tokens Yes
FORWARD_RULES Email forwarding rules No

Forwarding Rules Examples:

# Simple format:
FORWARD_RULES="support=help@company.com,sales=contact@company.com"

# JSON format:
FORWARD_RULES='[{"prefix":"urgent","email":"alerts@company.com"},{"prefix":"*","email":"archive@company.com"}]'

Complete API Reference

Mailbox Management

Endpoint Method Function
/api/generate GET Creates new temporary email
/api/mailboxes GET Lists all generated addresses
/api/mailbox/{address} DELETE Removes specific address

Email Operations

Endpoint Method Function
/api/emails?mailbox=ADDRESS GET Lists emails in a mailbox
/api/email/{id} GET Shows full email content
/api/email/{id} DELETE Deletes specific email
/api/emails?mailbox=ADDRESS DELETE Clears entire mailbox

Authentication

Endpoint Method Function
/api/session POST User login (returns JWT)
/api/logout POST Terminates session

System Information

Endpoint Method Function
/api/domains GET Lists available domains

Important Considerations

  1. Resource Caching: After updating HTML/CSS files, purge Cloudflare cache
  2. Asset Paths: Use relative paths for icons (e.g., favicon.svg)
  3. Email Routing: Verify MX records and catch-all configuration
  4. Database Management: Regularly purge expired emails
  5. Security: Always change default credentials in production

Customization Options

Easily modify these aspects:

  • Interface styling in public/ directory
  • Email generation patterns and length
  • Email retention periods
  • API endpoints for extended functionality

Troubleshooting Guide

Emails Not Arriving?

  1. Verify MX records in DNS settings
  2. Check Cloudflare Email Routing configuration
  3. Ensure domain in MAIL_DOMAIN matches your domain
  4. Confirm worker is deployed and active

Database Connection Issues?

# List databases:
wrangler d1 list

# Test connection:
wrangler d1 execute TEMP_MAIL_DB --command "SELECT 1"

Authentication Problems?

  1. Confirm ADMIN_PASSWORD secret is set
  2. Verify JWT_TOKEN matches your secret
  3. Clear browser cookies and local storage
  4. Check worker logs for errors

Interface Display Errors?

  1. Validate asset paths in HTML files
  2. Inspect browser console for JavaScript errors
  3. Ensure CSS files load properly
  4. Force refresh with Ctrl/Cmd + Shift + R

Auto-Refresh Not Working?

  1. Confirm an email address is selected
  2. Check browser supports Page Visibility API
  3. Verify stable network connection
  4. Test without browser extensions

Debugging Techniques

# View real-time logs:
wrangler tail

# Local debugging:
wrangler dev

# Database inspection:
wrangler d1 execute TEMP_MAIL_DB --command "SELECT * FROM emails"

Support and Contact

For technical assistance:
WeChat: iYear1213

Support Project Development

If this solution helps you, consider supporting the project:

Alipay Donation QR
WeChat Donation QR

License Information

This project uses the Apache License 2.0 – free for personal and commercial use with proper attribution.

Final Thoughts

This temporary email solution combines privacy protection with modern serverless technology. By leveraging Cloudflare’s global network and D1 database, you get a cost-effective, scalable service that protects your primary inbox from spam. Whether you’re safeguarding personal communications or building a privacy-focused application, this implementation provides a solid foundation you can customize to your specific needs.