電子郵件設定

EmDash 使用電子郵件進行魔法連結登入、使用者邀請和帳戶復原。供應商外掛傳送郵件；您透過安裝其外掛來選擇和設定供應商。

本指南涵蓋電子郵件管線的運作原理、開發中開箱即用的功能以及如何為生產環境連線真實供應商。

電子郵件傳送的運作原理

單一活動供應商外掛傳送所有出站郵件。如果沒有活動供應商，需要電子郵件的功能將不可用 — 邀請連結必須從使用者頁面手動複製和分享。

您可以在管理面板的 Settings → Email 下檢視目前狀態：供應商是否處於活動狀態、是哪個外掛，以及一個 send test email 按鈕，用於測試完整管線。

開發環境：內建主控台供應商

在開發環境（astro dev）中，當沒有選擇其他供應商時，EmDash 會自動啟用內建主控台供應商。它不傳送任何內容 — 它將每封電子郵件記錄到終端機，並將最後 100 則訊息保留在記憶體中。

這意味著魔法連結和邀請在開發環境中開箱即用：請求魔法連結，然後從終端機輸出中複製 URL。您還可以在僅限開發的端點 GET /_emdash/api/dev/emails 列出捕獲的電子郵件（並使用 DELETE 清除它們）。

主控台供應商僅用於開發，永遠不會在生產建置中執行。

生產環境：安裝供應商外掛

Cloudflare Workers

在 Cloudflare 上，使用 @emdash-cms/cloudflare/plugins 中的 cloudflareEmail() 外掛。它透過 Worker send_email 繫結透過 Cloudflare Email Sending 傳送，因此不需要外部帳戶或 API 金鑰。Cloudflare 部署指南將指導您完成寄件者網域的註冊、新增繫結和註冊外掛。

Node 和其他平台

社群維護的 emdash-smtp 外掛系列涵蓋通用 SMTP 加託管供應商，包括 Amazon SES、Brevo、Mailgun、Postmark、Resend、SendGrid、Zoho 等。

pnpm add emdash-smtp

以下設定將外掛註冊到 EmDash：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { emdashSmtp } from "emdash-smtp";

export default defineConfig({
	integrations: [
		emdash({
			// ...您的資料庫/儲存設定
			plugins: [emdashSmtp()],
		}),
	],
});

供應商憑證透過外掛自己的設定進行設定 — 有關供應商矩陣和設定詳細資訊，請參閱其 README。

供應商憑證的儲存位置

供應商外掛將其 API 金鑰和密碼宣告為外掛設定。在管理面板的外掛設定頁面中輸入它們；EmDash 將它們與其他外掛設定一起儲存在資料庫中，輪換金鑰意味著在那裡貼上新值。Secrets & Key Management 描述了儲存及其注意事項。

外掛是否可以讀取部署機密（wrangler secret put、.env）取決於其格式，因此請遵循其 README。沙盒外掛無法存取 process.env 或平台繫結。原生外掛可以讀取 process.env；它不得使用 import.meta.env，後者在建置時內聯並將建置機器的值烘焙到套件中。

選擇供應商並測試

安裝並啟用供應商外掛，然後在管理面板中開啟 Settings → Email。
如果安裝了多個供應商外掛，請在那裡選擇活動的一個 — 一次只有一個傳送。
使用 Send test email 端到端驗證完整管線。結果直接顯示傳送錯誤，這是偵錯憑證的最快方法。

故障排除

“No email provider is configured” — 沒有活動的供應商外掛。安裝並啟用一個，然後在 Settings → Email 中選擇它。
魔法連結/邀請悄然不可用 — 相同原因。沒有供應商，使用者頁面仍會建立邀請，但您必須手動複製邀請連結。
在開發環境中有效，在生產環境中失敗 — 開發環境使用內建主控台供應商，掩蓋了缺少的生產供應商。在部署的網站上檢查 Settings → Email。
電子郵件進入垃圾郵件 — 在您的電子郵件供應商處為您的傳送網域設定 SPF/DKIM/DMARC；這是供應商端的，不是 EmDash 設定。