synaplan的邮件能力分为入站webhook、imap邮箱处理、聊天中的只读邮箱搜索和出站smtp。给现有自托管实例增加邮件通道时，应先明确消息从哪里进入、通过什么服务回复，不把这四条路径当成一个开关。
用Webhook接收转发邮件
先在邮件服务器或中继中准备转发，将邮件内容交给/api/v1/webhooks/email。文档要求X-API-Key头以及JSON格式的发件人、收件人、主题和正文。下面是请求结构示例，密钥需换成该实例的有效值。
POST /api/v1/webhooks/email
X-API-Key:
Content-Type: application/json
{
"from": "sender@example.com",
"to": "smart+project@synaplan.net",
"subject": "项目资料问题",
"body": "请整理本次讨论的三个结论",
"attachments": []
}
理解主题地址的适用范围
内置地址解析器会把smart+project映射到持续的project会话；不同关键字对应不同主题线程。但文档明确限定内置解析支持的收件域，不能把示例中的域名随意换成自有域后就承诺关键字仍会生效。自建路由需另行验证实际中继和处理逻辑。
Synaplan原始邮件文档中的主题地址与会话映射说明
配置SMTP回复通道
MAILER_DSN=smtp://user:password@smtp.example.com:587
在backend/.env或生产部署配置中填写对应值。用户名和密码里的@、冒号、斜线、井号、问号、百分号及美元符号应按URL规则编码，避免DSN被拆错；生产Compose环境也应保留这一处理。
按需要增加IMAP或邮箱搜索
用户或部门邮箱的入站处理可在Manage、Channels、Email中配置。聊天中的实时只读搜索则依赖已有IMAP处理器或Microsoft 365连接，并不代表把整个收件箱复制进服务器。
发送与接收都验证成功后，再检查主题串联、附件及账号速率限制。示例地址与密钥仅用于说明格式，不是可直接使用的业务账户。
