メール設定

このページ

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_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 では保存前に送信者のメールアドレスの入力を求められます。

環境変数がそろっている場合、メールプロバイダープラグインがアクティブである、または 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を使用してはいけません。

プロバイダーの選択とテスト

  1. プロバイダープラグインをインストールしてアクティブ化し、管理画面でSettings → Emailを開きます。

  2. 複数のプロバイダープラグインがインストールされている場合、そこでアクティブなものを選択します — 一度に1つだけが配信します。

  3. Send test emailを使用して、完全なパイプラインをエンドツーエンドで検証します。結果は配信エラーを直接表示するため、認証情報をデバッグする最速の方法です。

トラブルシューティング

  • “No email provider is configured”:アクティブなプロバイダーがありません。SMTP を設定するか、プロバイダープラグインをアクティブ化してから、Settings → Email で選択します。
  • マジックリンク/招待が暗黙的に利用不可 — 同じ原因。プロバイダーがないと、ユーザーページは招待を作成しますが、招待リンクを手動でコピーする必要があります。
  • 開発環境では動作するが本番環境で失敗 — 開発環境は組み込みのコンソールプロバイダーを使用し、本番プロバイダーの欠落をマスクします。デプロイされたサイトでSettings → Emailを確認してください。
  • メールがスパムに振り分けられる — メールプロバイダーで送信ドメインのSPF/DKIM/DMARCを設定します;これはプロバイダー側で、EmDash設定ではありません。

関連