title: Mailbox SMTP 客户端配置
Mailbox SMTP 客户端配置
这页给出公开推荐参数、客户端映射关系和配置注意事项。
通用配置项
- 服务器：
smtp.agent-mx.taskpilots.net - 端口：
587 - 加密方式：
STARTTLS - 用户名：
<active-sender-identity> - 密码：
<mailbox-or-domain-token>
参数映射
| 参数 | 是否必填 | 推荐值 | 说明 |
|---|---|---|---|
SmtpServer |
必填 | smtp.agent-mx.taskpilots.net |
Submission 主机名 |
SmtpPort |
必填 | 587 |
Submission 端口 |
SmtpSecure |
必填 | false |
不使用直连 TLS |
SmtpStartTls |
必填 | true |
必须启用 STARTTLS |
SmtpUsername |
必填 | <active-sender-identity> |
active sender identity 地址 |
SmtpPassword |
必填 | <mailbox-or-domain-token> |
具备 MailboxSend 的 mailbox token 或 domain token |
FromName |
建议填写 | <display-name> |
显示名称 |
FromEmail |
必填 | <active-sender-identity> |
建议与本次 MAIL FROM 一致 |
ToEmail |
必填 | <recipient-email> |
收件人地址 |
字段说明
SmtpServer
- 用途：SMTP Submission 主机
- 格式：DNS 主机名
- 典型错误：误填为旧的内部主机或应用 HTTP 域名
SmtpPort
- 用途：SMTP Submission 端口
- 推荐值：
587 - 典型错误：误用
25或内部 relay 端口
SmtpSecure
- 用途：是否在连接建立时直接走 TLS
- 推荐值：
false - 原因：当前公开口径是
STARTTLS，不是 SMTPS 直连
SmtpStartTls
- 用途：是否启用
STARTTLS - 推荐值：
true - 典型错误：设为
false，导致认证前无法升级到 TLS
SmtpUsername
- 用途：SMTP AUTH 用户名
- 格式：active sender identity 地址
- 附加约束：必须是已存在且可解析的 mailbox 主地址或 active alias；如果使用
domain token，该地址还必须属于 token 自己的 domain - 典型错误：使用显示名、域名或当前 mailbox 不具备发送权限的其他地址
SmtpPassword
- 用途：SMTP AUTH 密码
- 格式：
mailbox token或domain token - 权限要求：必须具备
MailboxSend - 典型错误：使用无发信权限、已禁用或已过期的 token
FromName
- 用途：邮件显示名称
- 建议：填写业务名称或邮箱所有者名称
- 注意：这是头部显示名，不是 SMTP 登录名
FromEmail
- 用途：发件人邮箱头部地址
- 建议：与本次选择的
MAIL FROM一致 - 注意：平台要求
MAIL FROM与 MIMEFrom最终都落在已解析 mailbox 的 active sender identity 上；如果使用domain token，还必须属于 token 自己的 domain
ToEmail
- 用途：收件人地址
- 格式：合法邮箱地址
证书前置要求
默认情况下：
smtp.agent-mx.taskpilots.net:587应提供公网可信证书- 大多数标准客户端不需要额外导入根证书
只有在平台临时回退到自签名 fallback 时，才需要导入：
Windows / macOS / Linux / Docker 的导入命令见 TLS 与根证书。
不要通过关闭证书校验来绕过问题。
邮件客户端示例
- 发件服务器：
smtp.agent-mx.taskpilots.net - 发件端口：
587 - 加密方式：
STARTTLS - 用户名：
support@example.com - 密码：
<mailbox-or-domain-token>
如果这里使用的是 domain token，则示例里的 support@example.com 必须已经注册为该 domain 下某个 mailbox 的主地址或 active alias，不能替换成未注册地址。
部署补充说明
这条说明只用于部署和联调背景，不是给外部客户端直接操作的：
- 服务端优先从
/app_data/certs/smtp-submission-587/目录读取公网PFX - 如果优先证书不可用，再回退到
/app/certs/submission.pfx
更完整的部署真相源见：