Xi-Mail is a full-stack self-hosted email service built on Cloudflare Workers / D1 / KV / R2, developed as a secondary project based on the cloud-mail open-source project, featuring a comprehensive UI redesign and a suite of new features.
All you need is a domain hosted on Cloudflare to deploy a complete email platform for free, supporting multiple accounts, multiple domains, and hierarchical permissions.
What’s New & Changed From Upstream
Fully Redesigned UI (Linear Style)
- Frontend style system rebuilt with TailwindCSS 4 + @vueuse/motion animation library
- Login / Registration pages: frosted glass cards + dynamic gradient light glow + grid decorations
- Sidebar: dark minimalist style, unified icons
- Top bar: compact layout, gradient Compose button, optimized user info panel
- Global design tokens: indigo-violet gradient palette, colorful shadows, unified border radius
- Top bar language switch button: one-click switch between Chinese / English interfaces, applies in real-time and persists
Enhanced User System
- Display ID: User ID is now a random alphanumeric string (
xxxx-xxxx-xxxx), no longer just incremental numbers - Display ID shown in: user detail panel, personal settings page, top bar avatar hover card
- Mailbox Transfer: Users can transfer their email account and all associated emails to another user (specified by Display ID); recipient can accept or decline
Improved Account Management
- Inbox / Sent sidebar account list: added search filter, displays full email address (for easier distinction with multiple accounts)
- Account operation dropdown menu is always visible (including mailbox transfer entry)
- Sent / Drafts: If sending is not permitted or the role is prohibited from sending, these menus automatically hide from the sidebar
Transfer Function Page (/transfer)
- Dedicated sidebar page, supports initiating transfers, viewing pending / sent transfer requests
- Badge in the top bar shows number of pending requests in real time
Redesigned Permission System
- Roles gain a new
levelfield (the higher the value, the higher the permission) - Users can only generate invitation codes for roles with a lower level than their own
- Level constraints are rigorously validated server-side when generating invite codes
Bulk Operations (User Management)
- Supports bulk banning, unbanning, and deleting of selected users
- Supports bulk deletion of mailboxes associated with users
Enhanced System Settings
- Global API Token: Admins can enable and generate a global token, allowing direct querying of emails in a specified mailbox via
x-admin-authheader—no login needed (GET /api/admin/mails) - Email Address Keyword Blacklist: Prevents normal users from registering addresses containing sensitive keywords like
admin(admins can bypass this check) - Sender Domain Blacklist: Blocks senders from specified domains; emails are directly rejected by the system, effectively mitigating mail bombing
- Turnstile CAPTCHA Admin Exemption: When Turnstile is enabled, admins don’t need to complete CAPTCHA for registration or adding emails
- Invite Code Prompt & Link: When invite codes are enabled, configurable prompt text (e.g., «Contact admin to obtain») and a redirect link help new users learn how to get an invite code
- Improved announcement popup: Centered dialog display, customizable title/width/content, removed deprecated position/offset configs
- Optimized domain mapping UI (shows existing system domains for quick selection)
- Fixed alignment in auto-ban settings, removed redundant “login background” and “login opacity” settings
Improved Action Tooltips
- All action icons (search, refresh, sort, bulk operations, etc.) now consistently have tooltip hover prompts
Quick Deployment
Prerequisites
- Node.js ≥ 20
- Logged-in Cloudflare account:
npx wrangler login - A domain hosted on Cloudflare, with Email Routing set up
Steps
# 1. Clone the repository
git clone https://github.com/PastKing/xi-mail.git
cd xi-mail/mail-worker
# 2. Install dependencies
npm install
# 3. Create Cloudflare resources
npx wrangler d1 create xi-mail # Record the output database_id
npx wrangler kv namespace create kv # Record the output id
npx wrangler r2 bucket create xi-mail
# 4. Configure wrangler.toml
cp wrangler.example.toml wrangler.toml
# Edit wrangler.toml and enter the IDs, domain list, admin email, and JWT secret you obtained above
# 5. Build the frontend
cd ../mail-view
npm install
npm run build
# 6. Initialize database and deploy
cd ../mail-worker
npx wrangler deploy
# 7. Initialize database schema (visit after first deployment)
# In your browser, visit: https://your-worker.workers.dev/api/init/<JWT_SECRET>
wrangler.toml Key Field Descriptions
[vars]
domain = ["mail.example.com"] # Email domain list (JSON array)
admin = "[email protected]" # Admin email (cannot be changed after initial setup)
jwt_secret = "your-secret" # JWT signing key (minimum 32-character random string)
Global API Token
After enabling and generating a token in System Settings → Security → Global API Token, emails can be queried via the following endpoint without login:
GET /api/admin/mails?limit=20&offset=0&[email protected]
x-admin-auth: <your-token>
Response format:
{
"results": [...],
"count": 100
}
Project URL