Trigger Email 拡張機能の使用

Trigger Email 拡張機能（firestore-send-email）を使用すると、Cloud Firestore コレクション内のドキュメントに基づいてメールを自動的に送信できます。コレクションにドキュメントを追加すると、この拡張機能がトリガーされ、ドキュメントのフィールドの情報に基づいてメールが生成され、送信されます。ドキュメントの最上位のフィールドにはメールの送信者と受信者を指定します。受信者には to、cc、bcc のオプションがあります（いずれも UID をサポートしています）。ドキュメントの message フィールドには、件名やメール本文（平文または HTML）などのメール要素を指定します。

この拡張機能をトリガーするドキュメントの書き込みの基本的な例を紹介します。

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

この拡張機能のオプションの構成によって、Handlebars テンプレートを使用してメールを生成することもできます。

インストール前の設定

この拡張機能をインストールする前に、次の手順を行ってください。

1. 送信メールサービスを設定します。

   Trigger Email 拡張機能をインストールするときに SMTP サーバーの接続と認証に関する情報を指定する必要があります。この拡張機能はそれらの情報を使用してメールを送信します。通常、メール送信機能は Sendgrid、Mailgun、Mailchimp Transactional Email などのメール配信サービスによって提供されますが、自社で運用するサーバーも使用できます。

2. メール ドキュメント コレクションを作成します。

   Trigger Email 拡張機能は、指定された Cloud Firestore コレクション内の新しいドキュメントをリッスンします。新しいドキュメントを検出すると、この拡張機能はドキュメントのフィールドに基づいてメールを送信します。そのために任意の Cloud Firestore コレクションを使用できます。このページの例では、email という名前のコレクションを使用しています。

3. メール ドキュメント コレクションのセキュリティ ルールを設定します。

   この拡張機能を使用すると、クライアント アプリケーションからメール配信を直接トリガーできます。ただし、不正使用を防止するため、コレクションへのクライアント アクセスは慎重に管理する必要があります（貴社の企業アドレスでユーザーが任意のメールを送信できるようでは問題になります）。

   セキュリティ ルールはアプリケーションごとに異なりますが、メールは必ず目的の受信者に対してのみ送信され、自由形式のコンテンツは最小限に抑えるようにする必要があります。ここでテンプレートが役に立ちます。セキュリティ ルールを使用すると、テンプレートに入力されるデータと、ユーザーにトリガーが許可されるべき処理とが一致していることを確認できます。

4. 省略可: ユーザー コレクションを設定します。

   この拡張機能の基本的な使用法では、メッセージ ドキュメントの to、cc、bcc フィールドにメールアドレスを指定することによって、メールの受信者を指定します。別の方法として、Cloud Firestore にユーザー データベースがある場合は、ユーザーの UID を使用して受信者を指定することもできます。この方法を使用するには、ユーザー コレクションが次の条件を満たしている必要があります。

   • コレクションのキーはユーザー ID に基づくものである必要があります。つまり、コレクション内の各ユーザー ドキュメントのドキュメント ID は、ユーザーの Firebase Authentication にする必要があります。
   • 各ユーザー ドキュメントには、ユーザーのメールアドレスを含む email フィールドが必要です。

5. 省略可: テンプレート コレクションを設定します。

   Handlebars テンプレートを使用してメールを作成できます。これを行うには、テンプレートを格納する Cloud Firestore コレクションが必要です。

   詳しくは、Trigger Email 拡張機能で Handlebars テンプレートを使用するをご覧ください。

拡張機能をインストールする

この拡張機能をインストールするには、Firebase Extension のインストール ページの手順に従います。簡単に説明すると、次のいずれかの方法でインストールします。

• Firebase コンソール: 次のボタンをクリックします。

  Trigger Email 拡張機能をインストールする

• CLI: 次のコマンドを実行します。

  firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

拡張機能をインストールするときに、SMTP 接続の情報と、上記の手順で設定した Cloud Firestore コレクションを指定するように求められます。

拡張機能を使用する

この拡張機能をインストールすると、構成したコレクションに対するすべてのドキュメントの書き込みがモニタリングされます。ドキュメントのフィールドの内容に基づいてメールが配信されます。最上位のフィールドにはメールの送信者と受信者を指定します。message フィールドには、配信されるメールの詳細情報を指定します。メールの本文はここに指定します。

例: メールを送信する

単純なメッセージを送信するには、to フィールドと message フィールドに以下の内容を指定して、ドキュメントをメッセージ コレクションに追加します。

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

送信者と受信者のフィールド

ドキュメントの最上位フィールドには、メールの送信者と受信者の情報を指定します。使用可能なフィールドは次のとおりです。

• from: 送信者のメールアドレス。ドキュメント内で指定されていない場合は、構成されている「Default FROM address」パラメータが使用されます。
• replyTo: 返信先メールアドレス。ドキュメント内で指定されていない場合は、構成されている「Default REPLY-TO address」パラメータが使用されます。
• to: 単一の受信者メールアドレス、または複数の受信者メールアドレスを含む配列。
• toUids: 受信者の UID を含む配列。
• cc: 単一の受信者メールアドレス、または複数の受信者メールアドレスを含む配列。
• ccUids: CC 受信者の UID を含む配列。
• bcc: 単一の受信者メールアドレス、または複数の受信者メールアドレスを含む配列。
• bccUids: BCC 受信者の UID を含む配列。
• headers: 追加のヘッダー フィールドのオブジェクト（例: {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}）。

注: toUids、ccUids、bccUids の各オプションを使用すると、ユーザーの UID に基づいてメールを配信します。この UID をキーとして、Cloud Firestore ドキュメント内に指定されたメールアドレスが取得されます。これらの受信者オプションを使用するには、この拡張機能の「Users collection」パラメータで Cloud Firestore コレクションを指定する必要があります。この指定を行うことによって、toUids、ccUids、bccUids フィールドに指定された各 UID の email フィールドを読み取ることができます。

メッセージ フィールド

ドキュメントの message フィールドにはメールの具体的な配信情報を指定します。通常、このフィールドのデータ設定は、自社サーバーまたは Cloud Functions で実行される信頼されたコードのみによって行う必要があります（下の「セキュリティ ルールとメールの送信」セクションをご覧ください）。

message フィールドで使用可能なプロパティは次のとおりです。

• messageId: メールのメッセージ ID ヘッダー（ある場合）。
• subject: メールの件名。
• text: メールの平文コンテンツ。
• html: メールの HTML コンテンツ。
• amp: メールの AMP4EMAIL コンテンツ。
• attachments: 添付ファイルを含む配列。Nodemailer のオプションがサポートされており、次の要素を使用できます。utf-8 文字列、カスタム コンテンツ タイプ、URL、エンコードされた文字列、データ URI、事前生成された MIME ノード（メールからクラウド サーバーのファイル システムにアクセスできないことに注意してください）。

高度な授業・利用向け

以下のページでは、この拡張機能の高度な使用方法を説明しています。

• Trigger Email 拡張機能で Handlebars テンプレートを使用する
• Trigger Email 拡張機能による配信ステータスの管理