OpenMail

A self-hosted, open-source mail server suite in a single Node.js process — full-stack email with SMTP / IMAP / POP3, a modern three-pane webmail, an admin dashboard, multi-tenancy, DKIM, anti-spam and 2FA. Zero native dependencies, one SQLite file, up and running in minutes.

简体中文文档

Why OpenMail

Most self-hosted mail stacks glue together a dozen daemons (Postfix, Dovecot, Rspamd, Redis, MySQL…). OpenMail is a deliberately simple, single-binary-style mail platform written entirely in JavaScript:

• One process runs SMTP (MX + Submission + SMTPS), IMAP, IMAPS, POP3, POP3S, the HTTP API and the webmail UI.
• Zero native modules — node:sqlite (built into Node.js 22+), pure-JS crypto. Installs in seconds on Windows, Linux, macOS, ARM64.
• Real protocols — Thunderbird / Apple Mail / Outlook can connect via IMAP/SMTP out of the box.
• Sane defaults — DKIM keys auto-generated per domain, DNS records rendered in the admin UI, spam scoring built in.

Feature matrix

Mail

Contacts

Accounts & security

Domains & multi-tenancy

Admin dashboard

Anti-spam & authentication

• Inbound authentication via SPF, DKIM and DMARC verification (mailauth)
• Rule-based spam scoring (auth failures, keywords, HELO checks…) → auto junk folder, optional SMTP-level rejection
• Outbound mail is DKIM-signed automatically using each domain's key
• Per-user and global sender blacklists
• Rate limiting per IP on all SMTP ports

Protocols

The IMAP/POP3 servers are intentionally minimal (LOGIN, LIST, SELECT, FETCH, STORE, SEARCH, APPEND, IDLE, MOVE…) — enough for everyday client use, not a full RFC 3501 implementation.

Installation

OpenMail ships four install paths — pick one:

| Method | Command / Entry | Best for | | --- | --- | --- | | One-click script | curl -fsSL https://raw.githubusercontent.com/chenyuwebwawa/OpenMail/main/install.sh \| bash | Fresh Linux VPS (installs Node 22, source, .env, systemd, language packs) | | Docker | docker compose up -d --build (source) · ghcr.io/chenyuwebwawa/openmail:latest / chenyutech/openmail:latest (prebuilt) | Any server with Docker / 1Panel | | Manual server | git clone && npm install && npm start | Development, Windows (see start-windows.bat), custom setups | | Hosting panels | BT Panel (宝塔) guide · 1Panel guide | Existing panel-managed servers |

1. One-click (Linux server)

# Interactive: prompts for domain, generates .env, registers a systemd service,
installs all 10 UI language packs and prints the admin password.
curl -fsSL https://raw.githubusercontent.com/chenyuwebwawa/OpenMail/main/install.sh | bash
Behind a network that blocks raw.githubusercontent (e.g. mainland China)? Any of:
curl -fsSL https://cdn.jsdelivr.net/gh/chenyuwebwawa/OpenMail@main/install.sh | bash
git clone https://github.com/chenyuwebwawa/OpenMail.git /opt/openmail && cd /opt/openmail && bash install.sh
Non-interactive with options:
bash install.sh --domain example.com --standard-ports --dir /opt/openmail

Updating later — one command on the server (backs up data, snapshots runtime files, pulls the latest code, installs deps, restarts):

cd /opt/openmail && bash scripts/update.sh      # add --check to preview new commits

Flags: --domain (mail domain), --standard-ports (use 25/587/… instead of dev ports), --port (HTTP), --dir (install dir). The server runs as a non-root user via systemd (systemctl status openmail).

2. Docker

OpenMail runs as a single container — SQLite and attachments live in bind mounts, no sidecars. Two ways to get the image:

Option A — build from source (recommended, always works):

git clone https://github.com/chenyuwebwawa/OpenMail.git && cd OpenMail
cp .env.example .env                # set domain / base URL / relay / TLS
docker compose up -d --build

docker-compose.yml reads every OM_* value from your .env (via ${VAR:-default}) instead of hardcoding it; the database, the auto-generated secret.key and admin-credentials.txt persist in ./data, attachments in ./files. The admin password is printed on first launch (also written to data/admin-credentials.txt).

Option B — prebuilt image (published automatically to GHCR and Docker Hub):

The Docker Image workflow builds multi-arch images (linux/amd64, linux/arm64) on every push to main, on v* tags and on manual dispatch, and publishes the same tags to both registries:

• GHCR — ghcr.io/chenyuwebwawa/openmail:latest (uses the built-in GITHUB_TOKEN, no secrets required)
• Docker Hub — chenyutech/openmail:latest (public, anonymous pull works; pushed via the maintainer's DOCKERHUB_USERNAME / DOCKERHUB_TOKEN repo secrets)

# if the package is private, log in first with a PAT that has read:packages:
docker login ghcr.io -u <github-user>
docker pull ghcr.io/chenyuwebwawa/openmail:latest
or from Docker Hub (public, anonymous pull works):
docker pull chenyutech/openmail:latest
docker run -d --name openmail --restart unless-stopped \
  -p 3000:3000 -p 25:25 -p 587:587 -p 465:465 \
  -p 143:143 -p 993:993 -p 110:110 -p 995:995 \
  -v openmail-data:/app/data -v openmail-files:/app/files \
  -e OM_PRIMARY_DOMAIN=example.com -e OM_BASE_URL=https://mail.example.com \
  ghcr.io/chenyuwebwawa/openmail:latest   # or: chenyutech/openmail:latest

OM_SECRET is optional: leave it unset and the first boot generates a key, persisted to /app/data/secret.key inside the data volume (so recreating the container keeps saved AI keys working). If you set it explicitly, keep it fixed — changing it invalidates every saved AI API key.

Or use the prebuilt image through Compose (no local build):

# use either registry — both expose the same tags
echo "OPENMAIL_IMAGE=ghcr.io/chenyuwebwawa/openmail:latest" >> .env
echo "OPENMAIL_IMAGE=chenyutech/openmail:latest" >> .env
docker compose up -d

Image not available? Images are built by GitHub Actions and published to GHCR, and — when the repo secrets DOCKERHUB_USERNAME + DOCKERHUB_TOKEN are configured (as they are for this repository) — to Docker Hub as docker.io/chenyutech/openmail (public, multi-arch, anonymous pull). On a brand-new fork the packages may not exist yet: use Option A, or run Actions → Docker Image → Run workflow once; for anonymous GHCR pulls, set the package visibility to Public under repo → Packages → Package settings.

> Healthcheck: the image probes the public route GET / (HTTP 200) every 30 s, so docker compose ps shows healthy once the app is up. Upgrades: docker compose pull && docker compose up -d for the prebuilt image, or git pull && docker compose up -d --build for source builds (source installs use scripts/update.sh instead).

> Full Docker guide — GHCR/Docker Hub publishing, ports & firewall, reverse-proxy TLS, backups, multi-arch and troubleshooting: docs/DOCKER.md.

3. Manual

Requirements: Node.js ≥ 22.5 (no native build tools needed).

git clone https://github.com/chenyuwebwawa/OpenMail.git
cd OpenMail
npm install
npm start

First launch prints the auto-created admin credentials and writes them to data/admin-credentials.txt. On Windows, run start-windows.bat for a double-click launcher.

4. Hosting panels

• BT Panel (宝塔面板) — docs/panels/BAOTA.md: full walkthrough including the 宝塔邮局 (BT Mail plugin) adaptation — auto-detects port conflicts with Postfix/Dovecot, can take over mail services or co-exist on dev ports, reverse-proxy site setup, SSL reuse, and migration steps from BT Mail to OpenMail. One-shot adapter script: scripts/baota-adapt.sh.
• 1Panel — docs/panels/1PANEL.md: Docker-Compose orchestration, OpenResty reverse-proxy site, ACME certificates and firewall rules.

Production checklist

1. DNS — add A, MX, SPF, DKIM, DMARC records (the admin UI renders them for you; details in docs/DNS-Guide.md).
2. TLS — point OM_TLS_CERT / OM_TLS_KEY at a Let's Encrypt certificate (or terminate TLS at Nginx/Caddy). Self-signed certs are generated automatically for development.
3. Outbound relay — most clouds block outbound port 25. Configure OM_RELAY_* to route external mail through an upstream smarthost, or use a provider with port 25 open.
4. rDNS (PTR) — set a reverse DNS record on your server IP pointing to your mail hostname.
5. Backups — download SQLite snapshots from the admin UI and back up files/; see docs/DEPLOYMENT.md.

Interface languages (10)

The webmail and admin console ship with English and 简体中文 built in, plus 8 installable language packs (provided as separate content in langpacks/):

🇬🇧 English · 🇨🇳 简体中文 · 🇫🇷 Français · 🇪🇸 Español · 🇵🇹 Português · 🇷🇺 Русский · 🇸🇦 العربية · 🇮🇳 हिन्दी · 🇧🇩 বাংলা · 🇵🇰 اردو

Arabic and Urdu render the whole UI right-to-left automatically. Switch anytime in Settings → Language.

Install packs (any one of):

node scripts/install-langpacks.mjs --all        # CLI: install every pack
node scripts/install-langpacks.mjs fr ar ur     # CLI: specific packs
npm run langpacks                               # show status

or in the admin web UI (Settings → Language → Install), or by copying langpacks/.json → public/locales/. Missing keys fall back to English; see langpacks/README.md to write your own pack.

node server/setup.js                  # show help
node server/setup.js reset-admin [email protected] NewPass123
node server/setup.js add-domain example.org
node server/setup.js list-users

┌────────────────────────── one Node.js process ──────────────────────────┐
│  HTTP :3000          SMTP :25        Submission :587/465   IMAP :143/993│
│  ┌───────────┐      ┌─────────┐     ┌────────────┐       ┌──────────┐   │
│  │ Webmail   │      │ MX pipe │     │ SASL auth  │       │ Minimal  │   │
│  │ Admin UI  │      │ ▼       │     │ ▼          │       │ IMAP/POP3│   │
│  │ REST API  │      │ mailauth(SPF/DKIM/DMARC) + spam score          │   │
│  └─────┬─────┘      └────┬────┘     └─────┬──────┘       └────┬─────┘   │
│        │                 └───────┬────────┘                   │         │
│        ▼                         ▼                            ▼         │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                mailstore (folders, threads, quota, filters)      │  │
│  ├──────────────────────────────────────────────────────────────────┤  │
│  │   node:sqlite (WAL)             files/ attachments (per-user)    │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│  scheduler: scheduled send · outbound queue retry · bounce notices     │
└─────────────────────────────────────────────────────────────────────────┘

openmail/
├── .github/workflows/      # CI: build & publish multi-arch images to GHCR + Docker Hub
├── install.sh              # one-click installer (Node 22 + systemd + langpacks)
├── start-windows.bat       # Windows double-click launcher
├── scripts/                # update.sh (one-click updater) · doctor.sh (self-diagnosis) · install-langpacks.mjs · baota-adapt.sh (BT panel)
├── server/
│   ├── index.js            # entry: HTTP + all services + first-run init
│   ├── smtp.js             # MX / Submission / SMTPS servers
│   ├── imap.js             # minimal IMAP4rev1 server
│   ├── pop3.js             # POP3/POP3S server
│   ├── db.js               # node:sqlite schema + helpers
│   ├── config.js           # env config
│   ├── setup.js            # CLI maintenance tool
│   ├── util/               # TOTP, DKIM keys, TLS, sessions, RBAC
│   ├── mail/               # mailstore, delivery pipeline, outbound, scheduler
│   └── routes/             # auth / mail / contacts / settings / admin / langs APIs
├── public/                 # webmail + admin SPA (vanilla ES modules, no build)
│   ├── js/i18n.js          # i18n runtime (10 languages, RTL aware)
│   └── locales/            # installed language files (en + zh built in)
├── langpacks/              # extra language packs + installer manifest (8 languages)
├── scripts/
│   ├── install-langpacks.mjs
│   ├── update.sh — 一键更新
│   └── baota-adapt.sh      # BT Panel (宝塔) adapter incl. BT Mail plugin handling
├── tests/e2e.mjs           # 119-check offline e2e suite (API, SMTP, IMAP, POP3, i18n, mock-AI)
├── docs/                   # DNS guide, deployment guide, Docker guide (docs/DOCKER.md), panel guides, screenshots
├── Dockerfile · docker-compose.yml · .env.example

npm test            # 119-check offline e2e suite against a running server (mock AI upstream included)
npm run test:secret # verify the auto-generated OM_SECRET survives restarts
npm run dev         # node --watch auto-restart