メール送信の設定

Crowi はパスワードリセットや招待などの通知メールを送信できます。ストレージや検索と同様、メール送信は runner プロジェクトの crowi.config.json (mail.driver) で選択する メールドライバ を通じて行われ、ドライバの実体は @crowi/plugin-mail-* プラグインが提供します。

設定の置き場所は 2 つに分かれています。送信元アドレス (from) だけがコアの設定 で、管理画面のメール設定画面 (/admin/mail) から編集します。 ドライバごとの接続情報・認証情報 (SMTP ホスト / 認証、Resend の API キー、 SES の AWS 認証情報) は各プラグインの設定 で、/admin/plugins から編集します。

指定できるドライバ名と提供プラグインの対応は crowi.config.json にあります。@crowi/plugin-mail-smtp は暗黙のデフォルトプラグインなので、smtp ドライバは設定なしで利用できます。SES や Resend を使う場合は、対応するプラグインを runner プロジェクトに追加し、mail.driver をそれに合わせて設定します。

Note: メール設定は必須ではありません。送信元アドレスとアクティブなドライバの接続情報が揃うまで、メール送信を伴う操作はエラーになります。

メーラーの選択ロジック

送信方式は crowi.config.json の mail.driver (デフォルト smtp) で決まり、対応する @crowi/plugin-mail-* プラグインが起動時にそのドライバを登録します。実際の送信時には、その時点でアクティブなドライバがプラグインレジストリから解決されます。

送信に必要なものは 2 つあります。

送信元アドレス (mail:from) は すべてのドライバで必須 です。管理画面の /admin/mail で設定します。
アクティブなドライバには、それぞれ固有の設定も必要です — 例えば SMTP ドライバには SMTP ホスト、SES ドライバには AWS のリージョンと認証情報が必要です。これらは /admin/plugins の各プラグイン設定で入力します。

どちらも設定変更後に サーバを再起動する必要はありません。送信元アドレスを保存するとメールサービスが作り直され、プラグイン設定を保存すると該当プラグインが新しい接続情報をすぐに読み直します。

Note: メール本文中の招待 / アクティベーション / パスワードリセット / メールアドレス変更のリンクは絶対 URL である必要があるため、CLIENT_URL が設定されていないとリンクが機能しません。詳しくは環境変数の CLIENT_URL の行を参照してください。

管理画面でのメール設定

/admin/mail を開くと、次の 3 つが表示されます。

設定項目	内容
送信元アドレス	メールの送信元 (例: `crowi@example.com`)。この画面で編集できる唯一の項目です
有効なドライバ	いま使われているメールドライバ (例: `smtp`)。読み取り専用
提供元プラグイン	そのドライバを登録しているプラグイン。読み取り専用

プラグインは、接続情報を編集すべきプラグイン設定画面へのリンクとして表示されます。SMTP のホスト / 認証、Resend の API キー、SES の AWS 認証情報はこの画面には出てきません — それぞれのプラグイン設定にあります。

保存すると送信元アドレスが更新されます。

機密値の扱い

SMTP パスワードや Resend の API キーといった機密値は、プラグインの設定スキーマ側で @sensitive として宣言されており、プラグイン設定画面がマスク表示を担当します。

CROWI_ENCRYPTION_KEY が設定されていれば、これらの値は MongoDB に保存される際に自動で暗号化されます。未設定の場合は平文で保存されます。
仕組みの詳細はプラグインの導入と設定の「@sensitive マーカー」と機密設定の暗号化を参照してください。

SMTP で送信する

一般的な SMTP サーバ (Gmail, Mailgun, 自社メールサーバなど) を使う場合は、 @crowi/plugin-mail-smtp の設定 (/admin/plugins) に接続情報を入力します。このプラグインは暗黙のデフォルトなので、追加のインストールは不要です。

設定項目	値の例
送信元 (`from`)	`crowi@example.com` (`/admin/mail` 側)
`host`	`smtp.example.com`
`port`	`587` (STARTTLS) または `465` (SSL/TLS)。既定値は `587`
`user`	`crowi@example.com`
`password`	(SMTP サーバ側で発行したパスワード。機密扱い)
`secure`	最初から TLS で接続するか。既定 `false`

ポートに関する挙動:

ポート 465 を指定すると、secure の設定に関わらず暗黙 TLS で接続します。
それ以外のポート (例: 587) では、secure が false のまま STARTTLS でのアップグレードが試みられます。
host が空のままだとこのドライバは送信できません。
SMTP ユーザーとパスワードの両方が設定されている場合のみ、SMTP 認証 (AUTH) が有効になります。どちらか片方だけだと認証なしで接続します。

AWS SES を使う場合は、@crowi/plugin-mail-aws-ses を runner プロジェクトに追加し、crowi.config.json の mail.driver を ses に設定します。 SES の認証情報は SES プラグイン自身ではなく @crowi/plugin-aws (管理サイドバーの「共通サービス」) の設定 から読み込まれるため、リージョンとアクセスキーはそちらに入力します。

設定項目	値の例
送信元 (`from`)	`crowi@example.com` (SES で検証済みのアドレス。`/admin/mail` 側)
`@crowi/plugin-aws` の `region`	`us-east-1`
`@crowi/plugin-aws` の `accessKeyId`	(SES 送信権限を持つ IAM ユーザーのキー)
`@crowi/plugin-aws` の `secretAccessKey`	(同上。機密扱い)

Tip: accessKeyId と secretAccessKey を 両方とも空のままにすると、 AWS SDK の既定の資格情報チェーン (IAM ロール / 環境変数 / 共有 credentials ファイル) が使われます。EC2 / ECS などでインスタンスロールを割り当てて運用する場合は、キーを入力せずそちらに任せられます。

Tip: SES はサンドボックス状態だと検証済みアドレス宛にしか送信できません。本番運用ではサンドボックス解除を AWS に申請してください。また、送信元アドレスは SES 側で検証済みである必要があります。

Note: @crowi/plugin-mail-aws-ses は SESv2 SDK で直接送信 します (SMTP relay ではありません)。そのため SES の SMTP 認証情報 (SMTP password) は不要 で、通常の IAM アクセスキー (SES 送信権限つき) を上記の画面に入れるだけで送れます。AWS Lightsail 上で動かす場合は、インスタンスロール (AmazonLightsailInstanceRole) があなたの AWS アカウントとは別アカウントに属するため、自分のアカウントで作った 明示的な IAM ユーザーのアクセスキー を設定する必要があります。Lightsail での通し手順は AWS Lightsail で動かすを参照してください。

Resend で送信する

Resend を使う場合は、@crowi/plugin-mail-resend を runner プロジェクトに追加し、mail.driver を resend に設定したうえで、プラグイン設定の apiKey に Resend の API キー (機密扱い) を入力します。

テストメールを送る

メール設定が正しいかは、管理画面の テスト送信 機能で確認できます。 操作中の管理者自身のメールアドレス宛 にテストメールが送信されます。

テスト送信は 保存済みの設定だけ を使います。画面で入力中のまだ保存していない値は使われないので、先に保存してから実行してください。
送信元アドレス (mail:from) が未設定の場合は 502 (MAIL_FROM_NOT_CONFIGURED) になり、画面にメール設定画面へのリンク付きでその旨が表示されます。それ以外の送信失敗 (ネットワークエラー・認証失敗など) はすべて 502 (MAIL_TEST_FAILED) の汎用メッセージになります。実際の接続エラーやドライバ側の詳細なエラー文字列は画面には表示されず、API サーバのログにだけ記録されます — 原因を特定するにはサーバログを確認してください。
テストメールは、他の通知メールと同じブランド付き HTML テンプレートで送られます。実際の通知メールがどう届くかをそのまま確認できます。

Note: テストメールの宛先は固定で「操作中の管理者のメールアドレス」です。任意の宛先を指定することはできません。テストする管理者アカウントに有効なメールアドレスが登録されている必要があります。

メールリンクの有効期限と使い切り

Crowi が送るメールのうち、リンクを開いて操作を完了させる 4 種類は、それぞれ有効期限と「一度使ったあとどうなるか」が決まっています。

メールの種類	有効期限	使い切りの扱い
招待	7 日	受諾済みのユーザーのリンクは `409` になり、二重受諾はできません。再送すると新しいリンクが発行されますが、古いリンクを明示的に無効化する必要はありません
アカウント有効化	24 時間	アカウントが有効になった時点で無効です。すでに有効なアカウントのリンクを開いてもサインインはされず、「リンクが無効」の画面になります
パスワードリセット	1 時間	1 回使うと無効になります。本人がパスワードを変更した場合と、管理者が管理画面からリセットした場合も、送信済みのリンクはすべて無効になります。さらにリンクは送信先のアドレスに紐付いているため、送信後にアカウントのメールアドレスが変わった場合も無効になります
メールアドレス変更	24 時間	変更が確定した時点で無効です (古いリンクで元のアドレスへ戻されることはありません)。加えて、申請したセッションが失われた時点でも無効になります — 本人のパスワード変更・パスワードリセットの完了・管理者によるパスワードリセットは、いずれも確認待ちの変更を取り消します

有効期限は署名されたトークン自体に埋め込まれており、DB には保存されません。期限内であっても、上記の条件を満たしたリンクは無効になります。

Note: パスワードリセットの申請 (「パスワードを忘れた場合」からの送信) 自体は、既存のリンクを無効化しません。メールアドレスさえ知っていれば他人の有効なリンクを潰せてしまうため、意図的にそうしています。無効化が起きるのは、リンクが実際に使われたとき・パスワードが変更またはリセットされたとき (本人・管理者いずれの操作でも)・アカウントのメールアドレスが変わったときです。

トラブルシューティング

症状	確認すること
メールがまったく送られない	`/admin/mail` で送信元アドレスが設定されているか。有効なドライバが期待するものになっているか。そのプラグインの接続情報が入力されているか
テスト送信が `502` になる	`MAIL_FROM_NOT_CONFIGURED` なら `/admin/mail` で `from` を設定する。`MAIL_TEST_FAILED` なら SMTP ホスト / ポート・認証情報・ファイアウォールでの送信ポート遮断を確認する (詳細な原因は API サーバのログに記録される)
認証エラーになる	SMTP ユーザーとパスワードの両方が入力されているか。パスワードを空のまま保存して未設定になっていないか
設定変更が反映されない	保存時に反映されるため通常は即時。それでも反映されない場合は API を再起動
メール内のリンクが壊れている	`CLIENT_URL` が公開 URL に設定されているか

次のステップ

環境変数 — 変数名・既定値・意味の一覧
機密設定の暗号化 — SMTP パスワード / SES キーの暗号化
管理画面 — 管理画面の全体像
通知 — ユーザー向けの通知機能