ObjectOS配置
邮件
配置事务性邮件投递的 Provider 和模板。
邮件
当应用需要时（密码重置、邀请、审批通知、定时报告），ObjectOS 通过框架的邮件插件发送事务性邮件。该插件内置三种传输方式。
传输方式
| Provider | 适用场景 | 必需环境变量 |
|---|---|---|
log | 本地开发；将邮件打印到 stdout 而不实际发送 | 无 |
resend | 通过 Resend 实现 SaaS 投递 | OS_EMAIL_API_KEY |
postmark | 通过 Postmark 实现 SaaS 投递 | OS_EMAIL_API_KEY |
默认是 log。当配置了真实 Provider 但未提供 API Key 时，ObjectOS 会回退到 log 传输——便于让非生产环境不会意外发出邮件。
关于 SMTP
运行时目前未内置原生 SMTP 传输。如果你的环境必须使用 SMTP（企业中继、本地邮件、内网/离线部署），有两种生产级方案：
- 在 ObjectOS 前部署 SMTP-to-API 中继。 Resend、Postmark 以及自托管替代品（Postal、Cuttlefish）都能接收 SMTP 并通过其 HTTP API 重新投递 —— ObjectOS 仍照常用 HTTPS 与它们交互。
- 以自定义邮件插件运行运行时。 邮件插件 API 很小（一个
send(message)函数）；在项目插件中包装nodemailer，通过requires列表接入。参见 spec 仓库中的 插件开发指南。
原生 SMTP 传输在 roadmap 中；进展见 github.com/objectstack-ai/objectos/issues。
环境变量
| 变量 | 用途 |
|---|---|
OS_EMAIL_PROVIDER | log、resend 或 postmark |
OS_EMAIL_API_KEY | Provider API Key（Resend 或 Postmark） |
OS_EMAIL_FROM | 默认发件人。支持 addr@x 和 Name <addr@x> 两种格式 |
OS_EMAIL_RETRIES | 发送失败的传输重试次数（默认 0） |
环境变量优先于 artifact 中 email 配置块的同名值，因此运维可以无需重建 artifact 即可重定向投递。
模板
可复用模板存放在 sys_email_template。模板支持框架模板引擎评估的变量插值。应用代码（或流程）以模板 id 和变量包调用邮件服务；服务渲染主题/正文并交给配置的传输方式。
验证投递
对 Resend / Postmark，验证发送域名已在 Provider 控制台中配置（SPF、DKIM，可选 DMARC）。最快的端到端检查是邮件设置页的 Send test email 操作——它使用真实传输方式并把传输错误就地呈现。
运维建议
- 把 API Key 当作 secret。存于客户的 secret manager，永不放入 artifact。
- 关注传输错误日志：Provider 限流、抑制名单与退信都会出现在那里。
- 对审计敏感的事务邮件（密码重置、MFA 挑战）应按客户策略保留——在审计日志上设置保留期，而不是在传输层。
- 出站邮件不阻塞业务事务：发送失败会被报告为错误，但不会回滚触发邮件的记录变更。