メール / SMTP 設定
メール送信とテスト送信の設定
Crowi はパスワードリセットや招待などの通知メールを送信できます。ストレージや
検索と同様、メール送信はランナープロジェクトの crowi.config.json
(mail.driver) で選択する メールドライバ を通じて行われ、ドライバの
実体は @crowi/plugin-mail-* プラグインが提供します。ドライバごとの認証情報
(SMTP パスワード、SES / Resend のキー、送信元アドレス) は管理画面のメール
設定画面 (/admin/mail) から入力します。
mail.driver | 提供プラグイン | 送信方式 |
|---|---|---|
smtp (デフォルト) | @crowi/plugin-mail-smtp (暗黙のデフォルト) | 一般的な SMTP サーバ |
ses | @crowi/plugin-mail-aws-ses | AWS SES |
resend | @crowi/plugin-mail-resend | Resend |
@crowi/plugin-mail-smtp は暗黙のデフォルトプラグインなので、smtp
ドライバは設定なしで利用できます。SES や Resend を使う場合は、対応する
プラグインをランナープロジェクトに追加し、mail.driver をそれに合わせて
設定します。
Note: メール設定は必須ではありません。アクティブなドライバに送信元 アドレスと認証情報が設定されるまでは、メーラーは初期化されず、メール 送信を伴う操作は「メーラーが未設定」というエラーになります。
メーラーの選択ロジック
送信方式は crowi.config.json の mail.driver (デフォルト smtp) で
決まり、対応する @crowi/plugin-mail-* プラグインが起動時にそのドライバを
登録します。管理画面のメール設定は、アクティブなドライバが必要とする認証
情報を供給します。
API は起動時 (および設定保存時) に、送信に十分な設定が揃っている場合のみ アクティブなメールドライバを初期化します。
- 送信元アドレス (
mail:from) は すべてのドライバで必須 です。未設定の 間はメーラーは初期化されません (メール機能オフ)。 - アクティブなドライバには、それぞれ固有の設定も必要です — 例えば SMTP ドライバには SMTP ホストとポート、SES ドライバには AWS リージョンと 認証情報が必要です。これらが欠けているとメーラーは初期化されません。
管理画面でのメール設定
/admin/mail を開くと現在のメール設定が表示されます。内部的には
GET /api/v2/admin/mail で次の値が取得されます。
| 設定項目 | 内容 |
|---|---|
from | 送信元メールアドレス (例: crowi@example.com) |
smtpHost | SMTP サーバのホスト名 |
smtpPort | SMTP サーバのポート番号 |
smtpUser | SMTP 認証のユーザー名 |
smtpPassword | SMTP 認証のパスワード (機密) |
aws.region | SES のリージョン |
aws.accessKeyId | SES 用 AWS アクセスキー ID |
aws.secretAccessKey | SES 用 AWS シークレットアクセスキー (機密) |
設定を保存すると PUT /api/v2/admin/mail が呼ばれ、保存後に
setupMailer() が再実行されます。そのため、サーバを再起動しなくても
新しいメール設定が即座に反映されます。
機密値の扱い
smtpPassword と aws.secretAccessKey は機密設定として扱われます。
- 取得時 (
GET) には実際の値は返らず、値が設定済みかどうか (hasValue) だけが返ります。 - 保存時、入力欄を空のまま送信した項目は 変更なし として扱われ、 既存の値が保持されます。明示的に空文字を送ると値がクリアされます。
CROWI_ENCRYPTION_KEYが設定されていれば、これらの値は MongoDB に 保存される際に自動で暗号化されます。詳細は 機密設定の暗号化 を参照してください。
SMTP で送信する
一般的な SMTP サーバ (Gmail, Mailgun, 自社メールサーバなど) を使う場合の 設定例です。
| 設定項目 | 値の例 |
|---|---|
送信元 (from) | crowi@example.com |
| SMTP ホスト | smtp.example.com |
| SMTP ポート | 587 (STARTTLS) または 465 (SSL/TLS) |
| SMTP ユーザー | crowi@example.com |
| SMTP パスワード | (SMTP サーバ側で発行したパスワード) |
ポートに関する挙動:
- ポート
465を指定すると、接続は自動的にsecure: true(SSL/TLS) になります。 - それ以外のポート (例:
587) では、STARTTLS でのアップグレードが 試みられます。 - SMTP ユーザーとパスワードの両方が設定されている場合のみ、SMTP 認証 (AUTH) が有効になります。どちらか片方だけだと認証なしで接続します。
AWS SES で送信する
AWS SES を使う場合は、@crowi/plugin-mail-aws-ses をランナープロジェクトに
追加し、crowi.config.json の mail.driver を ses に設定したうえで、
管理画面で SES のリージョンとクレデンシャルを設定します。
| 設定項目 | 値の例 |
|---|---|
送信元 (from) | crowi@example.com (SES で検証済みのアドレス) |
| AWS リージョン | us-east-1 |
| アクセスキー ID | (SES 送信権限を持つ IAM ユーザーのキー) |
| シークレットアクセスキー | (同上) |
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 で動かす を参照してください。
テストメールを送る
メール設定が正しいかは、管理画面の テスト送信 機能で確認できます。
これは POST /api/v2/admin/mail/test を呼び出し、操作中の管理者
自身のメールアドレス宛 にテストメールを送信します。
- テスト送信には、保存済みの設定値、または画面で入力中の SMTP 設定が 使われます。
- SMTP ホスト / ポートが設定されていない場合は
502エラーになります。 - ネットワークエラーや認証失敗も
502(MAIL_TEST_FAILED) として メッセージ付きで返ります。エラーメッセージを手がかりに設定を見直して ください。 - テストメールの件名・本文は固定の ASCII テキストです。文字エンコーディング 設定が誤っていても受信トレイに届くようになっています。
Note: テストメールの宛先は固定で「操作中の管理者のメールアドレス」 です。任意の宛先を指定することはできません。テストする管理者アカウントに 有効なメールアドレスが登録されている必要があります。
トラブルシューティング
| 症状 | 確認すること |
|---|---|
| メールがまったく送られない | mail:from が設定されているか。SMTP / SES のどちらかが完全に設定されているか |
テスト送信が 502 になる | SMTP ホスト / ポートが正しいか。認証情報が正しいか。ファイアウォールで送信ポートが塞がれていないか |
| 認証エラーになる | SMTP ユーザーとパスワードの両方が入力されているか。パスワードを空のまま保存して未設定になっていないか |
| 設定変更が反映されない | 保存後に setupMailer() が走るため通常は即時反映される。それでも反映されない場合は API を再起動 |