XMmail 使用文档
XMmail 是面向海量收件场景设计的自建邮箱系统，聚焦“只收不发”。文档基于当前项目能力整理，适用于部署上线、后台日常管理、第三方查询接入与问题排查。
测试与访问入口
可先通过演示地址熟悉系统结构，再进行本地或服务器部署。演示信息建议仅用于测试体验。
按宝塔面板流程完成 XMmail 部署
XMmail 支持按宝塔面板方式快速落地。推荐部署顺序为：安装面板、上传项目文件、添加并启动 Go 项目、提交机器码完成授权、开放服务端口，最后通过前后台地址完成联通性验证。
先在服务器安装宝塔面板，通过面板统一管理项目目录、运行环境、日志与端口策略。官方下载入口可使用 https://www.bt.cn/new/download.html。
在宝塔文件管理中选择根目录或新建项目目录，上传 XMmail 文件。随后进入网站 / 项目管理，选择 Go 项目 并完成项目添加。
项目添加完成后先启动服务，再进入项目日志查看机器码，并将该机器码提交给管理员完成授权。授权完成后，再放行端口并访问系统进行验证。
- 安装宝塔面板并完成基础初始化。
- 在文件管理中选择根目录，或自行创建文件夹用于存放 XMmail 文件。
- 上传项目文件后，进入宝塔面板中的 Go 项目管理并添加项目。
- 项目添加完成后直接启动。
- 打开项目日志，复制其中显示的机器码并提交管理员完成授权。
- 在防火墙中开放 25 / 110 / 143 / 8080 端口。
- 访问后台 http://服务器IP:8080/admin/login 和前台 http://服务器IP:8080/ 检查服务状态。
- 如需绑定域名，可在后续通过反向代理方式接入。
- 项目启动后需要先从项目日志中获取机器码，再进入授权流程。
- 建议按 25、110、143、8080 端口完成放行，确保收件与后台访问正常。
- 后台访问地址为 http://服务器IP:8080/admin/login。
- 前台访问地址为 http://服务器IP:8080/。
- 需要绑定域名时，可通过反向代理接入现有访问域名。
- 如需获取源码与进一步部署资料，可按现有渠道联系项目管理员。
- 宝塔面板已安装，项目目录已创建并上传完整文件。
- Go 项目已在宝塔中添加并成功启动。
- 项目日志中的机器码已提交，授权状态正常。
- 25 / 110 / 143 / 8080 端口已在防火墙放行。
- 后台地址与前台地址均可正常打开。
- 如需对外域名访问，已补充反向代理配置。
DB_TYPE=sqlite DB_DATABASE=data.db # 切换 MySQL 时可配置以下字段 # DB_TYPE=mysql # DB_HOST=127.0.0.1 # DB_PORT=3306 # DB_USER=root # DB_PASSWORD=your_password # DB_DATABASE=xmmail # DB_CHARSET=utf8mb4
# 启动后默认服务端口 SMTP : 25 IMAP : 143 POP3 : 110 管理服务 : 8000 Web 后台 : 8080 后台地址 : http://localhost:8080/admin/login 邮箱页 : http://localhost:8080
- 生产环境优先确认 25 / 110 / 143 / 8080 端口已放行。
- 域名接入前先完成 A / MX 解析配置，再创建域名和邮箱。
- 高并发场景建议优先使用 MySQL 模式，便于连接池与多实例扩展。
- SQLite 模式默认启用 WAL、busy_timeout 与缓存参数。
- MySQL 模式默认设置更高连接池，适合更大规模收件负载。
- 程序启动时会自动创建域名、邮箱、消息、临时邮箱、Token 与日志相关表。
围绕收件流程设计的后台工作台
Web 后台入口为 /admin/login。登录后可进入仪表板、邮箱管理、域名管理、实时邮箱、临时邮箱、安全中心、收件日志、品牌设置等模块。
查看邮箱总数、域名总数、邮件总数，并从快捷入口进入管理邮箱、管理域名、批量创建与实时邮箱页面。
新增域名、批量导入、批量删除，支持泛邮箱、DNS 提示以及“允许临时邮箱”开关。
支持搜索、按域名筛选、区分正常邮箱 / 临时邮箱、批量改密、导出与批量删除。
三栏式结构：左侧域名，中间邮箱 / 邮件列表，右侧邮件详情与附件下载，适合快速查看收件状态。
提供即时生成、自动过期、倒计时与邮件自动刷新能力，适用于注册验证、测试回执等场景。
通过黑白名单、关键字拦截与账户收件控制管理风险；通过收件日志按协议、主题、发件人筛查问题。
- 先添加域名，完成 DNS 解析。
- 再批量创建或导入邮箱。
- 通过实时邮箱检查新邮件是否正常进入。
- 需要外部查询时，再配置 Token 授权或验证码提取链接。
- 安全中心可按账户维度控制是否继续收件。
- 品牌设置可自定义登录页 Logo 与工作台视觉。
- 后台还提供更新页、API 文档页与管理员密码修改功能。
支持后台接口、授权查询与验证码提取
系统同时提供后台接口与外部调用能力。后台页面主要使用 /admin/api/* 接口；外部查询场景可结合 Token 授权、临时邮箱接口与验证码提取链接使用。
后台域名列表接口，实时邮箱左侧域名列表与域名管理页面会使用该类接口获取数据。
按域名获取邮箱列表，用于实时邮箱三栏查看器的中间列数据。
获取指定邮箱的邮件列表，适合用于收件状态检查与邮件轮询查看。
获取单封邮件详情，包含正文与附件下载入口，适合内部业务查信使用。
生成临时邮箱；配套还有 /api/temp-mail/mails、/api/temp-mail/mail/{id} 等接口。
结合后台创建的验证码提取链接使用，对外输出指定邮箱的提取结果，适合自动化接码场景。
系统内置 xm_query_tokens 与查询日志结构，可为第三方系统分配 Token、设置每日限额，并记录访问行为。适合将邮件查询能力有限度开放给业务侧。
后台可创建提取链接规则，系统会将来源邮箱、提取规则、输出结果与访问次数记录到独立表中，适用于验证码提取与内容采集场景。
典型接入思路 1. 业务系统创建邮箱或使用临时邮箱接口生成地址 2. 外部服务向该地址发送邮件 3. XMmail 通过实时邮箱或查询接口读取收件结果 4. 若是验证码场景，可直接使用提取链接输出验证码内容 5. 若需审计，可在收件日志与查询日志中回溯访问行为
部署与使用中常见问题排查
下面列的是搭建自建收件邮箱系统时最常见的几个问题，建议优先按这些方向排查。
先检查域名 A / MX 解析是否正确，再检查 25 端口是否开放、服务是否已启动，以及目标邮箱是否被设置为禁止收件。
测试、小规模部署可先用 SQLite；海量邮箱、高并发、需要更强扩展能力时，建议切换 MySQL。
检查后台登录状态是否有效，确认目标域名 / 邮箱已创建，并查看收件日志确认邮件是否已写入系统。
适合注册验证、回执测试、验证码采集等短时收件场景；正式长期邮箱建议走正常邮箱管理流程。
建议只暴露必须的查询接口，配合 Token、限额、访问日志使用，不要直接将后台认证接口暴露给第三方。
可依次检查后台是否可登录、实时邮箱是否可读取、收件日志是否新增记录、临时邮箱与提取链接是否返回结果。