MailGo

A modern, self-hosted email client with a clean web interface. Connect your IMAP/SMTP accounts and manage all your email from one place.

一个现代化的自托管 Web 邮件客户端，支持多账户 IMAP/SMTP，统一管理所有邮件。

Installation / 安装

Docker (Recommended / 推荐)

curl -fsSL https://raw.githubusercontent.com/MengMengCode/MailGo/main/install.sh | bash

The script downloads docker-compose.yml, generates .env with random secrets, pulls the pre-built image from GHCR, starts all containers (app + MySQL + Redis), and prints the initial login password.

脚本自动下载 docker-compose.yml，生成含随机密钥的 .env，从 GHCR 拉取预构建镜像，启动所有容器（应用 + MySQL + Redis），并打印初始登录密码。

Default install directory: ~/mailgo. Override with MAILGO_DIR=/path/to/dir.

默认安装目录：~/mailgo。可通过 MAILGO_DIR=/path/to/dir 自定义。

Binary Release / 二进制 Release 部署

Use this when you want to run MailGo itself as a normal Linux binary instead of a Docker container. The binary already embeds the frontend, but it still requires MySQL 8.0 and Redis 7.

如果你不想把 MailGo 主程序跑在 Docker 里，可以下载 Release 二进制文件直接运行。 二进制文件已经内嵌前端页面，但仍然需要 MySQL 8.0 和 Redis 7。

# Pick one:
# Linux x86_64 / amd64
curl -L -o mailgo.tar.gz https://github.com/MengMengCode/MailGo/releases/latest/download/mailgo-linux-amd64.tar.gz

# Linux ARM64 / aarch64
curl -L -o mailgo.tar.gz https://github.com/MengMengCode/MailGo/releases/latest/download/mailgo-linux-arm64.tar.gz

mkdir -p mailgo
tar -xzf mailgo.tar.gz -C mailgo --strip-components=1
cd mailgo

cp .env.example .env
openssl rand -hex 32

Edit .env and set at least:

编辑 .env，至少设置这些项：

ENCRYPTION_KEY=PASTE_THE_64_HEX_CHARS_FROM_OPENSSL_HERE
SERVER_PORT=8080

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=mailgo
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=mailgo

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Then start MailGo:

然后启动 MailGo：

chmod +x ./mailgo
./mailgo

Open http://SERVER_IP:8080. The initial password is printed in stdout. To reset it later:

打开 http://服务器IP:8080。首次登录密码会打印在控制台。之后如需重置：

./mailgo -reset-password
# Restart the running MailGo process after reset.

Manual / 手动部署

Requirements / 环境要求: Go 1.25+, Node.js 20+, MySQL 8.0+, Redis 7+

cd frontend && npm install && npm run build
cp -r dist ../backend/frontend-dist
cd ../backend
cp ../.env.example ../.env   # Edit with your credentials
go build -o mailgo .
./mailgo

Features / 功能介绍

English

Area	What MailGo provides
Multi-account	Connect multiple IMAP/SMTP email accounts with a unified inbox, folder navigation, and per-account avatar & color tagging.
Compose & reply	Rich-text editor with formatting toolbar, inline images, drag-and-drop attachments, auto-save drafts, reply/reply-all/forward, and PGP encryption toggle.
PGP encryption	Generate RSA-4096 key pairs, encrypt outgoing messages, auto-decrypt incoming messages, manual private key import, and key management with download.
AI assistant	AI-powered compose panel for writing, translating, summarizing, and modifying emails. Supports OpenAI-compatible APIs with streaming responses.
Email tracking protection	Detect and block tracking pixels, read receipts, and beacons from known ESP domains. Configurable per-message allow/deny.
Customizable UI	Accent colors, background images or looping videos with frosted glass effect, sidebar transparency, font size, border radius, shadow intensity, animation speed, compact mode, and custom CSS injection.
Themes & i18n	Light, dark, and system theme with cross-device sync. Chinese and English interface with cross-device language sync.
Search & filter	Full-text search across subjects, senders, and body content. Filter by date range, sender, subject, and attachment presence.
Attachments	PDF preview with page navigation, image preview, inline CID image resolution, download, and 25MB upload support.
Security	Session auth with HttpOnly + SameSiteStrict cookies, login rate limiting with IP banning, AES-256-GCM encryption at rest, CSP headers, SSRF protection, and CORS restriction.

中文

模块	MailGo 提供的能力
多账户管理	支持连接多个 IMAP/SMTP 邮箱账户，统一收件箱、文件夹导航、按账户设置头像和标记颜色。
写信与回复	富文本编辑器带格式工具栏、内嵌图片、拖拽附件、自动保存草稿、回复/全部回复/转发、PGP 加密开关。
PGP 加密	生成 RSA-4096 密钥对，加密发出的邮件，自动解密收到的加密邮件，支持手动导入私钥和密钥下载管理。
AI 助手	AI 辅助撰写面板，支持编写、翻译、摘要和修改邮件，兼容 OpenAI 接口，流式响应。
邮件追踪防护	检测并拦截追踪像素、阅读回执和信标，覆盖主流 ESP 追踪域名，支持按邮件单独允许/拦截。
自定义界面	主题色、背景图片或循环视频毛玻璃效果、侧栏透明度、字体大小、圆角、阴影强度、动画速度、紧凑模式、自定义 CSS 注入。
主题与国际化	浅色、深色、跟随系统三种主题，跨设备同步。中英文界面，跨设备语言同步。
搜索与筛选	全文搜索主题、发件人和正文内容，按时间范围、发件人、主题、是否有附件筛选。
附件处理	PDF 预览含翻页、图片预览、内嵌 CID 图片解析、下载、25MB 上传支持。
安全防护	Session 认证 HttpOnly + SameSiteStrict Cookie、登录速率限制与 IP 封禁、AES-256-GCM 静态加密、CSP 安全头、SSRF 防护、CORS 限制。

Configuration / 配置

All configuration is via environment variables in .env:

所有配置通过 .env 环境变量设置：

Variable / 变量	Description / 说明	Default / 默认值
ENCRYPTION_KEY	AES-256 key for encrypting passwords at rest / 静态加密密钥	Auto-generated / 自动生成
SERVER_PORT	HTTP listen port / HTTP 监听端口	8080
MAILGO_DATA_DIR	Persistent file storage for uploaded backgrounds and avatars / 上传背景与头像的持久化文件目录	~/.mailgo (/data/mailgo in Docker / Docker 中为 /data/mailgo)
TRUSTED_PROXIES	Additional trusted reverse proxy IPs/CIDRs, comma-separated / 额外可信反代 IP 或 CIDR	Loopback only / 仅回环地址
MYSQL_HOST	MySQL host / MySQL 主机	mysql
MYSQL_PORT	MySQL port / MySQL 端口	3306
MYSQL_USER	MySQL user / MySQL 用户	mailgo
MYSQL_PASSWORD	MySQL password / MySQL 密码	—
MYSQL_DATABASE	MySQL database / MySQL 数据库	mailgo
MYSQL_ROOT_PASSWORD	MySQL root password / MySQL root 密码	—
MYSQL_INNODB_BUFFER_POOL_SIZE	MySQL InnoDB buffer pool size / MySQL InnoDB 缓冲池大小	256M
MYSQL_INNODB_LOG_FILE_SIZE	MySQL InnoDB redo log file size / MySQL InnoDB redo 日志大小	128M
MYSQL_INNODB_FLUSH_LOG_AT_TRX_COMMIT	MySQL flush policy; 2 is faster for small self-hosted servers / MySQL 刷盘策略，2 更适合小型自托管	2
MYSQL_MAX_CONNECTIONS	MySQL server max connections / MySQL 服务端最大连接数	50
MYSQL_MAX_OPEN_CONNS	MailGo database connection pool max open connections / MailGo 数据库连接池最大打开连接数	10
MYSQL_MAX_IDLE_CONNS	MailGo database connection pool max idle connections / MailGo 数据库连接池最大空闲连接数	5
REDIS_HOST	Redis host / Redis 主机	redis
REDIS_PORT	Redis port / Redis 端口	6379

Password Management / 密码管理

# First install — auto-generated, printed to stdout
# 首次安装 — 自动生成并打印到控制台
docker logs mailgo | grep Password

# Reset password and restart MailGo to apply it
# 重置密码并重启 MailGo 使新密码生效
docker exec mailgo /app/mailgo -reset-password && docker restart mailgo

# Change password (logged in) / 修改密码（已登录状态）
# Settings > Security > Change Password
# 设置 > 安全 > 修改密码

Microsoft Outlook OAuth2

Outlook.com, Hotmail, Live, and Microsoft 365 accounts use Microsoft OAuth2 instead of mailbox passwords. Configure the integration under Settings > Accounts > Microsoft OAuth before adding a Microsoft account.

Outlook.com、Hotmail、Live 和 Microsoft 365 邮箱使用 Microsoft OAuth2， 不能直接使用邮箱密码。添加微软邮箱前，请先在 设置 > 账户 > Microsoft OAuth 中完成配置。

Create an app registration in Microsoft Entra:

1. Select Accounts in any organizational directory and personal Microsoft accounts as the supported account type.
2. Under Authentication > Advanced settings, enable Allow public client flows. Device Code Flow is a public-client flow and does not transmit the client secret.
3. Add delegated Office 365 Exchange Online permissions: IMAP.AccessAsUser.All and SMTP.Send.
4. Create a client secret and copy its Value (not its Secret ID).
5. Save the Application (client) ID and secret value in MailGo as MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET.

MailGo requires both fields to be configured before it allows a detected Microsoft mailbox to be added. The secret is encrypted at rest and never sent back to the browser by the settings API. The Device Code protocol itself uses only the Client ID.

When adding the account, MailGo displays a Microsoft device code, verifies IMAP and SMTP using XOAUTH2 after authorization, encrypts the access and refresh tokens, and refreshes expired access tokens automatically.

Docker Compose

The default docker-compose.yml pulls the pre-built image from GHCR. MySQL and Redis are connected via an internal Docker network (no host port exposure).

默认 docker-compose.yml 从 GHCR 拉取预构建镜像。MySQL 和 Redis 通过 Docker 内部网络连接（不暴露端口到宿主机）。

# Start / 启动
docker compose up -d

# Stop / 停止
docker compose down

# Logs / 查看日志
docker compose logs -f mailgo

# Update / 更新
docker compose pull && docker compose up -d

To build from source (for development), use docker-compose.dev.yml:

如需从源码构建（开发用途），使用 docker-compose.dev.yml：

docker compose -f docker-compose.dev.yml up -d --build

Release / 版本发布

MailGo uses git tags as the release source of truth. When you push a tag like v0.2.1, GitHub Actions publishes Docker images to GHCR and uploads Linux binary release assets.

MailGo 使用 git tag 作为发布版本来源。推送 v0.2.1 这样的 tag 后，GitHub Actions 会发布 GHCR Docker 镜像，并上传 Linux 二进制 Release 包。

# 1. Update VERSION, frontend/package.json, frontend/package-lock.json,
#    and frontend/src/lib/version.ts.
git add -A
git commit -m "release: v0.2.1"
git tag -a v0.2.1 -m v0.2.1
git push origin main
git push origin v0.2.1

Before tagging, make sure VERSION, frontend/package.json, frontend/package-lock.json, and frontend/src/lib/version.ts all contain the same version. GHCR will show version tags such as:

打 tag 前请确保 VERSION、frontend/package.json、frontend/package-lock.json 和 frontend/src/lib/version.ts 都是同一个版本号。GHCR Packages 会显示这些版本 tag：

ghcr.io/mengmengcode/mailgo:v0.2.1
ghcr.io/mengmengcode/mailgo:0.2.1
ghcr.io/mengmengcode/mailgo:0.2
ghcr.io/mengmengcode/mailgo:latest

To pin Docker Compose to a specific release, set this in .env:

如果 Docker Compose 想固定到某个版本，在 .env 里设置：

MAILGO_IMAGE_TAG=0.2.1

Direct IP and reverse proxy / 公网 IP 与反向代理

A domain is not required. Direct access works at http://PUBLIC_IP:8080. The frontend uses same-origin relative API paths, so the same build also works behind Nginx or Caddy.

不强制绑定域名，可直接访问 http://公网IP:8080。前端 API 使用同源相对路径， 因此同一个构建也可用于 Nginx 或 Caddy 反代。

Example same-host Nginx configuration (works with an IP or a domain):

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Loopback proxies are trusted automatically. If the reverse proxy connects from another container or machine, set TRUSTED_PROXIES to its IP or CIDR, for example TRUSTED_PROXIES=172.18.0.0/16.

Technology Stack / 技术栈

• Backend: Go 1.25, gorilla/mux, go-imap, go-message, AES-256-GCM, go-redis
• Frontend: React 19, TypeScript 5, Vite 8, Tailwind CSS 3, openpgp, lucide-react, PDF.js
• Database: MySQL 8.0, Redis 7
• Deployment: Docker, Docker Compose, GitHub Actions

Architecture / 架构

┌──────────────────────────────────────────┐
│   Browser  (React + TypeScript + Vite)   │
└─────────────────┬────────────────────────┘
                  │ HTTP
┌─────────────────┴────────────────────────┐
│   Go Single Binary  (gorilla/mux)        │
│   ├── REST API        /api/v1/*          │
│   ├── IMAP Sync       go-imap            │
│   ├── SMTP Send       net/smtp           │
│   ├── AI Proxy        OpenAI-compatible  │
│   └── Static Serving  //go:embed         │
├────────────┬────────────┬────────────────┤
│   MySQL    │   Redis    │  IMAP / SMTP   │
│   (data)   │  (cache)   │  (mail servers)│
└────────────┴────────────┴────────────────┘

Preview / 预览

License / 开源许可

Apache License 2.0