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 挑戰）應按客戶策略保留——在審計日誌上設定保留期，而不是在傳輸層。
- 出站郵件不阻塞業務事務：傳送失敗會被報告為錯誤，但不會回滾觸發郵件的記錄變更。