電子郵件設定

本頁內容

EmDash 使用電子郵件進行魔法連結登入、使用者邀請和帳戶復原。由供應商傳送郵件:可以是 EmDash 內建的 SMTP 傳輸,也可以是供應商外掛。

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

電子郵件傳送的運作原理

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

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

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

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

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

如果在新增供應商外掛或設定 SMTP 之後,Settings → Email 仍顯示主控台,請在那裡選擇該供應商並儲存。

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

生產環境:內建 SMTP 傳輸

如果您有 SMTP 憑證(例如 Brevo、Office 365、Fastmail、Amazon SES 或您自己的郵件伺服器),EmDash 無需外掛即可透過它們傳送郵件。該傳輸在驗證之前要求使用 TLS,支援 AUTH PLAIN 和 AUTH LOGIN,並拒絕 25 連接埠。

您可以透過以下兩種方式之一進行設定:

  • 在管理後台: 開啟 Settings → Email,選擇 SMTP,填寫伺服器詳細資訊並儲存。儲存時會將設定存入資料庫並選取 SMTP。EmDash 使用 EMDASH_ENCRYPTION_KEY 加密密碼,因此必須設定該金鑰。在管理後台儲存的設定優先於環境變數,因此輪替密碼時請在管理後台修改。
  • 使用環境變數: 在伺服器的行程環境中設定以下變數。在 Cloudflare 上使用 wrangler secret put,本機開發使用 .env。在 Node 上,astro dev 和建置後的伺服器都不會載入 .env,因此請匯出這些變數,或使用 node --env-file=.env 啟動伺服器。請參閱 Secrets & Key Management。
變數範例說明
EMAIL_SMTP_HOSTsmtp.example.com必填
EMAIL_SMTP_PORT587選填;預設 587。隱式 TLS 使用 465
EMAIL_SMTP_USER[email protected]必填;SMTP 登入名稱
EMAIL_SMTP_PASSyour-smtp-password必填;請將其存為密鑰
EMAIL_SMTP_SECUREtls 或 starttls選填;465 連接埠使用 tls,其他所有連接埠使用 starttls
EMAIL_SMTP_FROMMy Site <[email protected]>選填的預設寄件者
EMAIL_SMTP_FROM_NAMEMy SiteEMAIL_SMTP_FROM_EMAIL 的選填顯示名稱
EMAIL_SMTP_FROM_EMAIL[email protected]選填的寄件者地址;優先於 EMAIL_SMTP_FROM
EMAIL_SMTP_REPLY_TO[email protected]選填的 Reply-To 地址

如果沒有設定寄件者變數,EmDash 會使用 EMAIL_SMTP_USER 作為寄件者。如果您的 SMTP 登入名稱不是電子郵件地址,請設定 EMAIL_SMTP_FROM_EMAIL 或 EMAIL_SMTP_FROM,否則投遞會失敗並提示 Invalid sender address for SMTP delivery。在這種情況下,Settings → Email 會在儲存前要求填寫寄件者電子郵件。

當環境變數完整時,EmDash 會透過 SMTP 傳送,除非有電子郵件供應商外掛處於活動狀態,或在 Settings → Email 中選擇了其他供應商。若要在使用供應商外掛的同時繼續使用 SMTP,請在那裡選擇 SMTP 並儲存。

在 Cloudflare Workers 上,該傳輸需要 nodejs_compat 相容性旗標。請參閱 Cloudflare 部署指南。

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

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,後者在建置時內聯並將建置機器的值烘焙到套件中。

選擇供應商並測試

  1. 安裝並啟用供應商外掛,然後在管理面板中開啟 Settings → Email。

  2. 如果安裝了多個供應商外掛,請在那裡選擇活動的一個 — 一次只有一個傳送。

  3. 使用 Send test email 端到端驗證完整管線。結果直接顯示傳送錯誤,這是偵錯憑證的最快方法。

故障排除

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

相關