Mailcow 快速入门（域名、邮箱与收发信实测）

前置：按部署指南篇完成 Mailcow 2026-09a 部署（HTTP 8126 / HTTPS 8130，管理端 http://mail.example.com:8126/admin，本域 example.com）。本文记录首次登录、管理端初始化、域名/邮箱/DKIM 创建与收发信全链路，全部操作在 2026-10-19 实测，回显真实。

一、环境信息

Mailcow 2026-09a（部署形态与端口见部署指南篇；SKIP_CLAMD/SOGO/FTS=y 降配运行）
管理端地址：http://mail.example.com:8126/admin（HTTPS 入口 https://mail.example.com:8130，自签证书浏览器需信任）
初始管理员：admin / moohoo（生成脚本注释原文 # Default password is "moohoo"）
演示域 example.com，演示邮箱 demo@example.com
本文操作路径以"管理端 + REST API + 命令行收发实测"展开，与管理端浏览器操作逐项对应

二、首次登录与强制改密向导

2.1 登录入口

Mailcow 管理端登录入口是 /admin（不带斜杠会 301 补斜杠）。首次以 admin / moohoo 登录，登录成功返回 302 跳转仪表盘：

POST /admin/ (login_user=admin, pass_user=……)
-> HTTP 302 Location: /admin/dashboard
GET  /admin/dashboard -> HTTP 200   <title>mail.example.com - mail UI</title>

浏览器访问时对应登录页的 "Login" 表单；/ 根路径登录表单仅校验普通邮箱用户角色，管理员必须走 /admin 入口（实测从根路径提交管理员凭据只会得到登录页回显，无报错——这是一个容易踩的交互点）。

2.2 强制改密向导（实测完整闭环）

管理账号存在 force_pw_update 属性（管理员编辑面板 "Force password update at next login" 勾选项）。置为待改密状态后再次登录，实测流程：

登录 POST 仍返回 302 Location: /admin（不是 dashboard）——被 pending 动作拦截；
/admin/ 页面弹出改密向导（Bootstrap Modal），页面标题不变、新增字段：

"Your account requires a password change. Please set a new password to continue."
<input id="changePWNew">      New password
<input id="changePWNew2">     Confirmation password (repeat)
<button>Save changes</button>

提交目标是管理 API（页面内联脚本实录）：

url = '/api/v1/edit/admin';
attrPayload = {password: newPw, password2: newPw2};
itemsPayload = [username];   // 'admin'

提交成功回显（* 为服务端对敏感值的脱敏）：

[{"type":"success","log":["admin","edit",{"username":["admin"],"password":"*","password2":"*"}],
  "msg":["admin_modified","admin"]}]

向导完成后重新访问 /admin/ 直接 302 进仪表盘（pending 状态清除），用新密码重新登录 302 → /admin/dashboard 成功。

演示环境约定：本文改密后管理密码为 q1w2e3r4。生产环境请勿使用示例口令。

2.3 管理端界面导览

登录后仪表盘（/admin/dashboard）自上而下：系统信息与服务状态卡（各组件健康与版本）、Mail 图表（投递量）、磁盘用量。左侧导航核心入口：

E-Mail → Configuration：域名、邮箱、别名、过滤器、DKIM 密钥
System → Configuration：管理员账户、访问列表、Rspamd 面板入口、日志
E-Mail → Logs：Postfix/Dovecot/Rspamd/SOGo 日志检索
Status：队列、磁盘、DNS 状态

三、开启 REST API（命令行管理的前提）

管理端与 API 共用一套权限。在 mailcow.conf 启用（2026-09a 中这三行默认处于注释状态，需取消注释并赋值）：

API_KEY=<随机生成的 48 位十六进制串>      # 读写密钥
API_KEY_READ_ONLY=                        # 只读密钥留空
API_ALLOW_FROM=127.0.0.1,10.89.54.0/24    # 来源白名单

随后必须重建让环境变量进容器（实测仅 docker compose up -d 不触发重建）：

$ docker compose up -d --force-recreate php-fpm-mailcow nginx-mailcow

验证：

$ curl -s -H "X-API-Key: <API_KEY>" http://127.0.0.1:8126/api/v1/get/status/version
{"version":"81f6f7b"}
$ curl -s -H "X-API-Key: <API_KEY>" http://127.0.0.1:8126/api/v1/get/domain/all
{}

坑位记录：白名单写 127.0.0.1 但从宿主 curl 容器映射端口时，php-fpm 看到的来源是编排网络网关（10.89.54.1），会持续返回 {"type":"error","msg":"authentication failed"}。白名单需加上编排网段（如 10.89.54.0/24）。密钥校验失败与来源拒绝在回执上不可区分，排查时先查来源。

四、创建域名与邮箱

4.1 创建域名（含配额坑）

$ curl -s -H "X-API-Key: <API_KEY>" -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","description":"Demo domain","maxquota":"4096","quota":"10240","mailboxes":"10","active":"1"}' \
  http://127.0.0.1:8126/api/v1/add/domain

成功回执（注意第一条——2026-09a 创建域名时自动生成 2048 位 DKIM 密钥）：

[{"type":"success","log":["dkim","add",{"key_size":2048,"dkim_selector":"dkim","domains":"example.com"}],
  "msg":["dkim_added","example.com"]},
 {"type":"success","log":["mailbox","add","domain",...],"msg":["domain_added","example.com"]}]

坑位记录：首次以 maxquota=1024 提交被拒： {"type":"danger",...,"msg":"mailbox_defquota_exceeds_mailbox_maxquota"} ——域名默认邮箱配额（defquota，默认 3072 MiB）不能超过单邮箱上限 maxquota。把 maxquota 提到 4096 后通过。浏览器操作对应 E-Mail → Configuration → Domains → Add domain 表单中的 Max quota 字段。

4.2 创建邮箱

$ curl -s -H "X-API-Key: <API_KEY>" -H 'Content-Type: application/json' \
  -d '{"local_part":"demo","domain":"example.com","password":"Xx9kPp2mQw7vTz4L","password2":"Xx9kPp2mQw7vTz4L","quota":"1024","active":"1","force_pw_update":"0","tls_enforce_in":"0","tls_enforce_out":"0"}' \
  http://127.0.0.1:8126/api/v1/add/mailbox
[{"type":"success",...,"msg":["mailbox_added","demo@example.com"]}]

浏览器操作对应 E-Mail → Configuration → Mailboxes → Add mailbox（本地部分 + 域选择 + 密码 + 配额）。创建回执中还会附一条 rl_saved（该邮箱限速值初始化）。

4.3 DKIM 密钥查询与 DNS 记录

$ curl -s -H "X-API-Key: <API_KEY>" http://127.0.0.1:8126/api/v1/get/dkim/example.com
{
    "pubkey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAo9sON303DdE01pXtbMn3UdbONXBj2Vi0OB8aB8EKv2GQERDceZcpiCF/eW8eCCGqNcjcBWlPtQQ+587//qKhnUcuyswHb1ShtPmjjWB3aVhCeHYUNdv8H/D/M0jAnBGFPn+hqtTm1jqU4pQonOEPZ/nGpKISuMqSEDN1sG0rbzuuLKzX0d2z/b4S3ZTlHXKqA15hmWipH0R0PMyUwUXI0SgK61ds+LiDDFo2d/3It9HwsHWXKMgEU8NdK/OLkRxlWm4NPnv1l0spvLOYzJzltzJeczVWHS1TMFbEgry0xkpHtaJr9iykmL2Nkuet6Ch3WbbZ3oYZ7Q..."
}

浏览器操作对应 Configuration → Configuration & Details → DKIM (Keys)。对外需发布 TXT 记录：主机名 dkim._domainkey.example.com，值为 v=DKIM1;k=rsa;p=<pubkey>。手动重生成可用 POST /api/v1/add/dkim（key_size/selector/domains 参数）。

五、收发信全链路实测

5.1 587 提交端口发信（STARTTLS + AUTH）

发信给自己（本地投递）：

$ swaks --to demo@example.com --from demo@example.com \
    --server 127.0.0.1:587 --tls \
    --auth LOGIN --auth-user demo@example.com --auth-password 'Xx9kPp2mQw7vTz4L' \
    --h-Subject 'Mailcow self delivery test'
...
 ~> Subject: Mailcow self delivery test
 ~> ...
<~  250 2.0.0 Ok: queued as 519ED108C2FE
<~  221 2.0.0 Bye

实测要点：587 在 TLS 建立前不广播 AUTH（明文 EHLO 能力表只有 250-STARTTLS 无 AUTH 行，swaks 第一次不带 --tls 报 Host did not advertise authentication）。这是 Postfix smtpd_tls_auth_only 安全默认——凭据只走加密通道。

投递日志（postfix 容器）可看到认证与队列轨迹：

postfix/submission/smtpd: 519ED108C29D...: client=unknown[10.89.54.1], sasl_method=LOGIN, sasl_username=demo@example.com
postfix/qmgr: 519ED108C2FE: from=<demo@example.com>, size=..., nrcpt=1 (queue active)

5.2 25 端口入站（模拟外部来信）

$ swaks --to demo@example.com --from sender@external.example.org \
    --server 127.0.0.1:25 --h-Subject 'Inbound from external domain'
<-  220 mail.example.com ESMTP Postcow

入站信会被 Rspamd 打上完整检查头（IMAP 取回实测）：

Return-Path: <sender@external.example.org>
Authentication-Results: mail.example.com;
        none
X-Rspamd-Queue-Id: 3CCE6108C313
X-Spamd-Result: default: False [0.90 / 15.00];
        R_MISSING_CHARSET(0.50)[];
        MIME_GOOD(-0.10)[text/plain];
        ARC_NA(0.00)[];
        CLAM_VIRUS_FAIL(0.00)[failed to scan and retransmits exceed];
        RCPT_MAILCOW_DOMAIN(0.00)[example.com];
        ...

Authentication-Results 为 none 是因为演示外域没有发布 SPF/DKIM/DMARC；CLAM_VIRUS_FAIL 是降配部署（关闭 ClamAV）后的预期降级标记。生产域名的三件套核查见运维手册篇。

5.3 993 端口收信（IMAPS）

$ curl -s -k --url 'imaps://127.0.0.1/INBOX' --user 'demo@example.com:Xx9kPp2mQw7vTz4L' \
    -X 'STATUS INBOX (MESSAGES UNSEEN)'
* STATUS INBOX (MESSAGES 1 UNSEEN 1)

用 IMAP 取第一封信的信头验证本地投递与签名：

Return-Path: <demo@example.com>
Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 519ED108C2FE
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; s=dkim;
To: demo@example.com
From: demo@example.com
Subject: Mailcow self delivery test

ESMTPSA 表明走的是认证+TLS 提交；DKIM-Signature（d=example.com; s=dkim）与 4.3 节生成的密钥对应，Rspamd 出站签名默认开启。

5.4 Webmail 说明

本环境以 SKIP_SOGO=y 部署（内存降配），SOGo Webmail/日历组件未启用，/SOGo 路径不可用。启用后浏览器访问 https://mail.example.com:8130/SOGo 用邮箱账号即可登录；管理端 ALLOW_ADMIN_EMAIL_LOGIN 变量还支持管理员以邮箱身份代理登录。

六、常见问题（入门期实测）

根路径登录管理员无反应：管理员入口在 /admin（2.1 节）。
API 恒报 authentication failed：先核对 API_ALLOW_FROM 是否包含真实来源网段（第三章坑位），再核对密钥。
add/domain 报 mailbox_defquota_exceeds_mailbox_maxquota：maxquota 需 ≥ 默认邮箱配额（4.1 节）。
587 无 AUTH：先 STARTTLS 再 AUTH（5.1 节），465 则为隐式 TLS。
创建域名后 DKIM 已自动生成：2026-09a 默认行为，重生成用 add/dkim（4.3 节）。

七、参考链接

官方文档 · First Steps：https://docs.mailcow.email/post_installation/firststeps-ssl/
官方 API 文档：https://docs.mailcow.email/api/
站内同族快速入门：《iRedMail 1.7.4 快速入门（域名、邮箱与收发信实测）》、《Postal 快速入门与实战示例》
本专栏部署篇：《Mailcow Docker Compose 部署指南》