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 を拒否します。
設定方法は次の 2 通りです。
- 管理画面で: 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_HOST | smtp.example.com | 必須 |
EMAIL_SMTP_PORT | 587 | 任意。デフォルトは 587。暗黙的 TLS には 465 を使用 |
EMAIL_SMTP_USER | [email protected] | 必須。SMTP のログイン |
EMAIL_SMTP_PASS | your-smtp-password | 必須。シークレットとして保存してください |
EMAIL_SMTP_SECURE | tls または starttls | 任意。ポート 465 は tls、それ以外のポートはすべて starttls を使用 |
EMAIL_SMTP_FROM | My Site <[email protected]> | 任意のデフォルト送信者 |
EMAIL_SMTP_FROM_NAME | My Site | EMAIL_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 では保存前に送信者のメールアドレスの入力を求められます。
環境変数がそろっている場合、メールプロバイダープラグインがアクティブである、または Settings → Email で別のプロバイダーが選択されている場合を除き、EmDash は SMTP 経由で送信します。プロバイダープラグインと併用して 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を使用してはいけません。
プロバイダーの選択とテスト
-
プロバイダープラグインをインストールしてアクティブ化し、管理画面でSettings → Emailを開きます。
-
複数のプロバイダープラグインがインストールされている場合、そこでアクティブなものを選択します — 一度に1つだけが配信します。
-
Send test emailを使用して、完全なパイプラインをエンドツーエンドで検証します。結果は配信エラーを直接表示するため、認証情報をデバッグする最速の方法です。
トラブルシューティング
- “No email provider is configured”:アクティブなプロバイダーがありません。SMTP を設定するか、プロバイダープラグインをアクティブ化してから、Settings → Email で選択します。
- マジックリンク/招待が暗黙的に利用不可 — 同じ原因。プロバイダーがないと、ユーザーページは招待を作成しますが、招待リンクを手動でコピーする必要があります。
- 開発環境では動作するが本番環境で失敗 — 開発環境は組み込みのコンソールプロバイダーを使用し、本番プロバイダーの欠落をマスクします。デプロイされたサイトでSettings → Emailを確認してください。
- メールがスパムに振り分けられる — メールプロバイダーで送信ドメインのSPF/DKIM/DMARCを設定します;これはプロバイダー側で、EmDash設定ではありません。
関連
- 認証 — メールに依存するマジックリンク、招待、回復フロー
- メールフックリファレンス —
email:beforeSend,email:deliver,email:afterSend