SkillAgentSearch skills...

Moemail

A cute temporary email service built with NextJS + Cloudflare technology stack 🎉 | 一个基于 NextJS + Cloudflare 技术栈构建的可爱临时邮箱服务🎉

GenerateConvertImprove

Install / Use

/learn @beilunyang/Moemail
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

<p align="center"> <img src="public/icons/icon-192x192.png" alt="MoeMail Logo" width="100" height="100"> <h1 align="center">MoeMail</h1> </p> <p align="center"> A cute temporary email service built with NextJS + Cloudflare technology stack 🎉 </p> <p align="center"> <span>English</span> | <a href="./README.zh-CN.md">简体中文</a> </p> <p align="center"> <a href="https://www.producthunt.com/products/moemail?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-moemail" target="_blank" rel="noopener noreferrer"><img alt="MoeMail - OpenAPI‑first temp email, hosted &amp; ready | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1078475&amp;theme=light&amp;t=1770964043604"></a> </p> <p align="center"> <a href="#live-demo">Live Demo</a> • <a href="#documentation">Documentation</a> • <a href="#features">Features</a> • <a href="#tech-stack">Tech Stack</a> • <a href="#local-run">Local Run</a> • <a href="#deployment">Deployment</a> • <a href="#email-domain-configuration">Email Domain Config</a> • <a href="#permission-system">Permission System</a> • <a href="#system-settings">System Settings</a> • <a href="#sending-emails">Sending Emails</a> • <a href="#webhook-integration">Webhook Integration</a> • <a href="#openapi">OpenAPI</a> • <a href="#cli-tool">CLI Tool</a> • <a href="#environment-variables">Environment Variables</a> • <a href="#github-oauth-app-configuration">Github OAuth Config</a> • <a href="#google-oauth-app-configuration">Google OAuth Config</a> • <a href="#contribution">Contribution</a> • <a href="#license">License</a> • <a href="#community">Community</a> • <a href="#support">Support</a> </p>

Live Demo

https://moemail.app

Home

Mailbox

Profile

Documentation

Full Documentation: https://docs.moemail.app

The documentation site contains detailed usage guides, API documentation, deployment tutorials, and other complete information.

Features

  • 🔒 Privacy Protection: Protect your real email address from spam and unnecessary subscriptions
  • ⚡ Real-time Receipt: Automatic polling, receive email notifications instantly
  • ⏱️ Flexible Validity: Supports 1 hour, 24 hours, 3 days, or permanent validity
  • 🎨 Theme Switching: Supports light and dark modes
  • 📱 Responsive Design: Perfectly adapted for desktop and mobile devices
  • 🔄 Auto Cleanup: Automatically cleans up expired mailboxes and emails
  • 📱 PWA Support: Support PWA installation
  • 💸 Free Self-hosting: Built on Cloudflare, capable of free self-hosting without any cost
  • 🎉 Cute UI: Simple and cute UI interface
  • 📤 Sending Function: Support sending emails using temporary addresses, based on Resend service
  • 🔔 Webhook Notification: Support receiving new email notifications via webhook
  • 🛡️ Permission System: Role-based access control system
  • 🔑 OpenAPI: Support accessing OpenAPI via API Key
  • 🤖 Agent-first CLI: CLI tool designed for AI agents to automate email workflows
  • 🌍 Multi-language Support: Supports Chinese and English interfaces, freely switchable

Tech Stack

Local Run

Prerequisites

  • Node.js 18+
  • Pnpm
  • Wrangler CLI
  • Cloudflare Account

Installation

  1. Clone the repository:
git clone https://github.com/beilunyang/moemail.git
cd moemail
  1. Install dependencies:
pnpm install
  1. Setup Wrangler:
cp wrangler.example.json wrangler.json
cp wrangler.email.example.json wrangler.email.json
cp wrangler.cleanup.example.json wrangler.cleanup.json

Set Cloudflare D1 database name and database ID.

  1. Setup Environment Variables:
cp .env.example .env.local

Set AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, AUTH_SECRET.

  1. Create local database schema:
pnpm db:migrate-local

Development

  1. Start development server:
pnpm dev
  1. Test Email Worker: Currently cannot run and test locally, please use Wrangler to deploy the email worker and test.
pnpm deploy:email
  1. Test Cleanup Worker:
pnpm dev:cleanup
pnpm test:cleanup
  1. Generate Mock Data (Mailboxes and Messages):
pnpm generate-test-data

Deployment

Video Tutorial

https://www.youtube.com/watch?v=Vcw3nqsq2-E

Local Wrangler Deployment

  1. Create .env file
cp .env.example .env

  1. Set Environment Variables in the .env file.

  2. Run deployment script

pnpm dlx tsx ./scripts/deploy/index.ts

Github Actions Deployment

This project supports automated deployment using GitHub Actions. It supports the following triggers:

  1. Auto Trigger: Automatically triggers deployment flow when a new tag is pushed.
  2. Manual Trigger: Manually trigger in the GitHub Actions page.

Deployment Steps

  1. Add the following Secrets in GitHub repository settings:

    • CLOUDFLARE_API_TOKEN: Cloudflare API Token
    • CLOUDFLARE_ACCOUNT_ID: Cloudflare Account ID
    • AUTH_GITHUB_ID: GitHub OAuth App ID
    • AUTH_GITHUB_SECRET: GitHub OAuth App Secret
    • AUTH_SECRET: NextAuth Secret, used to encrypt session, please set a random string
    • CUSTOM_DOMAIN: Custom domain for the website (Optional, if empty, uses Cloudflare Pages default domain)
    • PROJECT_NAME: Pages project name (Optional, if empty, defaults to moemail)
    • DATABASE_NAME: D1 database name (Optional, if empty, defaults to moemail-db)
    • KV_NAMESPACE_NAME: Cloudflare KV namespace name, used for site settings (Optional, if empty, defaults to moemail-kv)

  2. Choose trigger method:

    Method 1: Push Tag Trigger

    # Create a new tag
git tag v1.0.0

# Push tag to remote repository
git push origin v1.0.0

    Method 2: Manual Trigger

    • Go to the Actions page of the repository
    • Select "Deploy" workflow
    • Click "Run workflow"

  3. Deployment progress can be viewed in the Actions tab of the repository.

Notes

  • Ensure all Secrets are set correctly.
  • When using tag trigger, the tag must start with v (e.g., v1.0.0).

Deploy to Cloudflare Workers

Email Domain Configuration

In the MoeMail User Profile page, you can configure the site's email domains. Supports multiple domain configurations, separated by commas. Email Domain Configuration

Cloudflare Email Routing Configuration

To make email domains effective, you also need to configure email routing in the Cloudflare console to forward received emails to the Email Worker.

  1. Login to Cloudflare Console
  2. Select your domain
  3. Click "Email" -> "Email Routing" in the left menu
  4. If it shows "Email Routing is currently disabled", please click "Enable Email Routing" Enable Email Routing
  5. After clicking, it will prompt you to add Email Routing DNS records, click "Add records and enable" Add DNS Records
  6. Configure Routing Rules:
    • Catch-all address: Enable "Catch-all"
    • Edit Catch-all address
    • Action: Select "Send to Worker"
    • Destination: Select the "email-receiver-worker" you just deployed
    • Save Configure Routing Rules

Notes

  • Ensure domain DNS is hosted on Cloudflare.
  • Email Worker must be successfully deployed.
  • If Catch-All status is unavailable (stuck loading), please click Destination addresses next to Routing rules, and bind an email address there.

Permission System

The project uses a Role-Based Access Control (RBAC) system.

Role Configuration

New user default roles are configured by the Emperor in the site settings in the User Profile:

  • Duke: New users get temporary email, Webhook config permissions, and API Key management permissions.
  • Knight: New users get temporary email and Webhook config permissions.
  • Civilian: New users have no permissions, need to wait for Emperor to promote to Knight or Duke.

Role Levels

The system includes four role levels:

  1. Emperor

    • Website Owner
    • Has all permissions
    • Only one Emperor per site

  2. Duke

    • Super User
    • Can use temporary email features
    • Can configure Webhook
    • Can create API Key to call OpenAPI
    • Can be demoted to Knight or Civilian by Emperor

  3. Knight

    • Advanced User
    • Can use temporary email features
    • Can configure Webhook
    • Can be demoted to Civilian or promoted to Duke by Emperor

  4. Civilian

    • Regular User
    • No permissions
    • Can be promoted to Knight or Duke by Emperor

Role Upgra

beilunyang

View profile

View on GitHub
GitHub Stars2.3k
CategoryDevelopment
Updated1h ago
Forks1.9k
beilunyang/moemail

Languages

TypeScript

Security Score

100/100

Audited on Mar 30, 2026

No findings