title: Mailbox 参数规范

Mailbox 参数规范

这页统一说明公开集成的常见参数、格式要求、推荐值和典型错误。

连接参数

参数	是否必填	推荐值	说明	典型错误
`baseUrl`	HTTP / MCP 必填	`https://mailbox.feinian.net`	HTTP API 与 MCP 基址	填成内部地址或 SMTP 地址
`smtpServer`	SMTP 必填	`smtp.agent-mx.taskpilots.net`	Submission 主机名	填成旧主机或应用 HTTP 域名
`smtpPort`	SMTP 必填	`587`	Submission 端口	填成 `25` 或内部端口
`smtpSecure`	SMTP 必填	`false`	不使用直连 TLS	误设为 `true`
`smtpStartTls`	SMTP 必填	`true`	必须启用 STARTTLS	误设为 `false`
`caCertUrl`	fallback 时使用	`https://mailbox.feinian.net/ca.crt`	自签名 fallback 根证书下载地址	写成 `/app/certs/...`

认证参数

参数	是否必填	说明	与 token / scope 的关系	典型错误
`Authorization`	HTTP / MCP 必填	`Bearer <token>`	适用于 `mailbox token` 和 `domain token`	漏掉 `Bearer` 前缀
`token`	视接入方式而定	访问令牌	`mailbox token` 与 `domain token` 都可用于 SMTP；都必须具备 `MailboxSend`	用错 token 类型或 scope
`username`	SMTP 必填	SMTP AUTH 用户名	必须是已存在的 active sender identity 地址；`domain token` 时还必须属于 token 自己的 domain	用显示名、域名、未注册地址或越权地址代替邮箱地址
`password`	SMTP 必填	SMTP AUTH 密码	必须是具备 `MailboxSend` 的 `mailbox token` 或 `domain token`	用无发送权限、已禁用或已过期 token

邮件业务参数

参数	是否必填	格式要求	说明	典型错误
`mailboxAddress`	视 token 类型	邮箱地址	`domain token` 场景通常必填	省略或传入其他邮箱
`toAddress`	发信必填	邮箱地址	新邮件主收件人	地址格式非法
`ccAddresses`	可选	邮箱地址数组	抄送列表	数组里混入非法地址
`bccAddresses`	可选	邮箱地址数组	密送列表	数组里混入非法地址
`subject`	发信建议必填	1-200 字符	邮件主题	为空或超长
`bodyText`	必填	1-20000 字符	纯文本正文	为空
`attachmentIds`	可选	字符串数组	来自上传接口返回的 `attachmentUploadId`	直接放文件路径
`FromName`	建议填写	文本	发件显示名	误当成 SMTP 用户名
`FromEmail`	SMTP 建议必填	邮箱地址	头部发件地址	与本次 `MAIL FROM` 不一致导致混淆
`ToEmail`	SMTP 必填	邮箱地址	收件人地址	非法邮箱格式

SMTP 推荐参数

SmtpServer = smtp.agent-mx.taskpilots.net
SmtpPort = 587
SmtpSecure = false
SmtpStartTls = true
SmtpUsername = <active-sender-identity>
SmtpPassword = <mailbox-or-domain-token>
FromName = <display-name>
FromEmail = <active-sender-identity>
ToEmail = <recipient-email>

规则提醒

只有 fallback 自签名模式下，外部客户端才需要从 https://mailbox.feinian.net/ca.crt 下载根证书
/app/certs/ 是服务端运行时读取目录，不是客户端参数
SMTP Submission 接受 mailbox token 与 domain token
domain token 在 HTTP / MCP 场景通常需要显式给出 mailboxAddress
domain token 在 SMTP 场景只能使用其自身 domain 下已存在的 mailbox 主地址或 active alias