A modern, privacy-focused temporary email service powered entirely by Cloudflare's edge network.
Inspired by oiov/vmail. This project has been completely rewritten with modern technologies and enhanced features.
- 🔒 Privacy First - No registration required, anonymous by default
- 📧 Email Management - Receive and view emails instantly
- 🔐 Mailbox Claiming - Optionally claim mailboxes with password protection
- 🔍 OTP Detection - Automatic extraction and display of verification codes
- 🌐 Multiple Domains - Support for multiple email domain suffixes
- 🎨 Modern UI - Beautiful interface with light/dark mode support
- 📱 Responsive Design - Optimized for all screen sizes
- ⚡ Edge Performance - Lightning fast with Cloudflare's global network
- 🚀 100% Serverless - Runs entirely on Cloudflare (Workers + Pages + D1)
- 🛡️ Bot Protection - Integrated Cloudflare Turnstile
- 🎯 Type Safety - Full TypeScript implementation
- 🎭 Smooth Animations - Refined page transitions and interactions
- 📚 Built-in Documentation - MDX-powered docs system
- 🔧 Easy Deployment - One-command deployment to Cloudflare
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare Edge │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Email Worker │───▶│ Cloudflare │◀───│ Astro Pages │ │
│ │ (Receives) │ │ D1 │ │ (Frontend) │ │
│ └──────────────┘ │ (Storage) │ └──────────────┘ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Tech Stack:
- Frontend: Astro 5.14 + React 19 + Tailwind CSS 4
- Email Worker: Cloudflare Email Worker + postal-mime
- Database: Cloudflare D1 (SQLite)
- Authentication: JWT (jose)
- UI Components: Radix UI + shadcn/ui
- Validation: Zod + React Hook Form
- Node.js >= 18
- pnpm >= 8
- Cloudflare account with:
- Email routing enabled
- D1 database created
- Turnstile site configured
git clone https://github.com/yourusername/cloudflare-vmails.git
cd cloudflare-vmails
pnpm installCreate a D1 database:
cd apps/astro
wrangler d1 create vmail-dbApply database schema:
cd ../emails-worker
wrangler d1 execute vmail-db --file=../../packages/database/schema.sqlCreate apps/astro/wrangler.toml:
# :schema node_modules/wrangler/config-schema.json
name = "vmail-app"
compatibility_date = "2024-09-25"
pages_build_output_dir = "./dist"
[vars]
# Cloudflare Turnstile (https://dash.cloudflare.com/?to=/:account/turnstile)
TURNSTILE_SECRET = "your-turnstile-secret"
TURNSTILE_SITE_KEY = "your-turnstile-site-key"
# Email configuration
MAIL_DOMAIN = "your-domain.com"
# Security
JWT_SECRET = "your-random-jwt-secret-min-32-chars"
COOKIE_EXPIRES_IN_SECONDS = 86400 # 24 hours
# Site information
SITE_NAME = "Your VMail Service"
SITE_DESCRIPTION = "Privacy-focused temporary email service"
# Optional: Email sending via Mailgun
# MAILGUN_BASE_URL = "https://api.mailgun.net"
# MAILGUN_API_KEY = "your-mailgun-api-key"
# MAILGUN_SEND_DOMAIN = "your-mailgun-domain.com"
[[d1_databases]]
binding = "DB" # DO NOT CHANGE
database_name = "vmail-db"
database_id = "your-database-id"Create apps/emails-worker/wrangler.toml:
name = "vmail-email-worker"
compatibility_date = "2024-09-25"
main = "src/index.ts"
[[d1_databases]]
binding = "DB" # DO NOT CHANGE
database_name = "vmail-db"
database_id = "your-database-id"- Go to Cloudflare Dashboard
- Select your domain → Email → Email Routing
- Enable Email Routing
- Add a Catch-all route pointing to your email worker
# Start development servers
pnpm dev
# Or start individually
pnpm --filter astro dev # Frontend at http://localhost:4321
pnpm --filter email-worker dev # Email worker# Deploy email worker first
cd apps/emails-worker
pnpm deploy
# Deploy frontend
cd ../astro
pnpm deployemails/
├── apps/
│ ├── astro/ # Frontend application
│ │ ├── src/
│ │ │ ├── actions/ # Astro server actions
│ │ │ ├── components/ # React & Astro components
│ │ │ ├── content/ # MDX documentation
│ │ │ ├── layouts/ # Page layouts
│ │ │ ├── lib/ # Utilities
│ │ │ └── pages/ # Route pages
│ │ └── wrangler.toml
│ └── emails-worker/ # Email receiver worker
│ ├── src/
│ │ └── index.ts
│ └── wrangler.toml
└── packages/
└── database/ # Shared database package
├── dao.ts # Data access layer
├── db.ts # Database client
└── schema.sql # Database schema
Temporary Mailbox
- No registration required
- Valid for 24 hours (configurable)
- Anyone with the mailbox ID can access
Claimed Mailbox
- Password protected
- Permanent storage
- Private and secure
Automatically detects and extracts verification codes from emails:
- 6-digit codes (123456)
- Alphanumeric codes (A1B2C3)
- Time-sensitive OTP formats
- JWT-based authentication
- Cloudflare Turnstile bot protection
- CORS and rate limiting ready
- Password hashing for claimed mailboxes
- Automatic email expiration
The project uses Tailwind CSS 4 with CSS variables for theming. Customize colors in apps/astro/src/globals.css:
:root {
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
--primary: 0 0% 9%;
/* ... more variables */
}Add multiple domains in your wrangler.toml by setting up email routing for each domain and updating the MAIL_DOMAIN variable.
# Development
pnpm dev # Start all services
pnpm dev:apps # Start apps only
pnpm dev:packages # Build packages in watch mode
# Building
pnpm build # Build all packages and apps
pnpm build:apps # Build apps only
pnpm build:packages # Build packages only
# Type checking
pnpm type-check # Check types
pnpm type-check:watch # Check types in watch mode
# Linting
pnpm lint # Lint all projects
# Deployment
pnpm deploy # Build and deploy all
# Cleanup
pnpm clean # Clean all build outputsContributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by oiov/vmail
- Built with Astro
- UI components from shadcn/ui
- Powered by Cloudflare
If you have any questions or need help, please:
- Open an issue on GitHub
- Check the documentation
- Review existing issues and discussions
Made with ❤️ using Cloudflare's edge network