> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 電子郵件

事務模板、預覽工具與提供商介面卡。

## 閱讀您的第一條本地訊息，然後啟用傳送

事務性電子郵件是指由應用程式操作觸發的訊息，例如登入程式碼或任務結果。 Web 伺服器執行時，將 EMAIL_PROVIDER=local 保留在 apps/web/.env.local. 中 完成資料庫設定，在 /auth 請求登入程式碼，然後開啟 /mail-preview 並檢查最新訊息。此處顯示的本地訊息不是傳送到您的外部收件箱的電子郵件。

要傳送真實訊息，請選擇一個電子郵件提供商，建立其帳戶，驗證您控制的域並遵循其專用指南。將名為API的金鑰和發件人地址放入apps/web/.env.local中，儲存並重新啟動Web伺服器。請求一個新的登入程式碼，然後檢查提供商的傳送日誌和目標收件箱，包括垃圾郵件。域驗證和發件人批准可能需要時間。

如果訊息失敗，請在重複請求之前檢查傳送錯誤和發件人驗證。 /mail-preview 路由僅用於開發，在生產中返回 404。將營銷推廣活動與該交易發件人分開，以便時事通訊活動不會中斷帳戶驗證郵件。

[選擇郵件提供商和發件人地址](https://supastack.dev/zh-tw/docs/modules/email-configuration.md)

[啟用重新傳送傳送](https://supastack.dev/zh-tw/docs/web/setup-email.md)

[使用 AWS SDK 或 IAM SMTP 配置 Amazon SES](https://supastack.dev/zh-tw/docs/web/aws-ses.md)


## 讓事務性投遞保持獨立

郵件模組處理事務性產品訊息，包括認證與任務完成通知。營銷觸達屬於使用方產品自己的工作流，必須與這條事務性路徑保持分離。


## 配置投遞介面卡

確定性測試用本地介面卡。啟用外部投遞前，配置選定的生產介面卡及其服務端憑證。絕不要把郵件供應商金鑰放進客戶端配置或日誌。


## 獨立記錄投遞結果

生成的結果與它的完成郵件是兩個獨立結果。在聲稱訊息傳送成功之前檢查投遞記錄。測試投遞失敗時，不要把它當作生成失敗，也不要重複提交模型工作。


## 安裝與配置

EMAIL_PROVIDER=local 讓開發期間的投遞保持確定性。生產投遞從已配置的介面卡中選一個 —— Resend（RESEND_API_KEY）、AWS SES（AWS_REGION 加訪問金鑰）、Postmark、SendGrid、Mailgun、通用 SMTP 或 Brevo —— 並確認 EMAIL_FROM 與該供應商認可的發件身份一致。

所有模板位於 src/transactional-mail-templates.ts。僅開發可用的 /mail-preview 路由會渲染每個模板，讓改動通過視覺化審查，而不是靠真實發信。

```
EMAIL_PROVIDER=resend
EMAIL_FROM=Your Product <hello@yourdomain.com>
```


## 實現流程

認證程式碼、魔法連結、邀請、計費通知和任務完成郵件都通過同一個事務傳送者,以已解析語言環境的文本傳送。外展活動是獨立的產品關注點,永遠不會共享此路徑。

在編輯文本或佈局之前先在 mail-preview 中預覽模板;讓品牌值(名稱、顏色、徽標拼塊)來自配置,這樣衍生產品可以在不 fork 模板的情況下重新設計樣式。


## 驗證與排障

在測試中對本地介面卡記錄的訊息進行斷言 —— 收件人、主題和渲染後的正文。傳送失敗應表現為投遞結果,而不是崩潰的工作流。使用帶 REAL_SMOKE_EMAIL_ALLOWED_DOMAIN 的可選 smoke 路徑進行真實投遞。


## 下一篇

[通知](https://supastack.dev/zh-tw/docs/web/notifications.md)