使用觸發電子郵件額外資訊

透過「觸發電子郵件」擴充功能 (firestore-send-email)，您可以根據Cloud Firestore集合中的文件自動傳送電子郵件。將文件新增至集合會觸發這項擴充功能，使其傳送根據文件欄位所建立的電子郵件。文件頂層欄位會指定電子郵件的寄件者和收件者，包括 to、cc 和 bcc 選項 (每個都支援 UID)。文件中的 message 欄位會指定其他電子郵件元素，例如主旨和電子郵件內文 (純文字或 HTML)。

以下是會觸發這項擴充功能的基礎文件寫入作業範例：

admin.firestore().collection('mail').add({
  to: '[e-mail]',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

您也可以選擇設定這項擴充功能，使用 Handlebars 範本呈現電子郵件。

預先安裝設定

安裝擴充功能前，請先完成下列步驟：

1. 設定外寄郵件服務。

   安裝「觸發電子郵件」擴充功能時，您需要指定 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 UID。
   • 每份使用者文件都必須含有 email 欄位，其中包含使用者的電子郵件地址。

5. 選用：設定範本集合。

   您可以使用 Handlebars 範本呈現電子郵件。 如要這麼做，您需要建立 Cloud Firestore 集合來存放範本。

   詳情請參閱「使用 Handlebars 範本搭配 Trigger Email 擴充功能」。

安裝擴充功能

如要安裝擴充功能，請按照「Firebase Extension」安裝頁面的步驟操作。總之，請執行下列任一操作：

• Firebase 控制台：點選以下按鈕：

  安裝「觸發電子郵件」擴充功能

• CLI：執行下列指令：

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

安裝擴充功能時，系統會提示您指定 SMTP 連線資訊和先前設定的 Cloud Firestore 集合。

使用擴充功能

安裝完成後，這項擴充功能會監控您設定的集合中所有文件的寫入作業。系統會根據文件欄位內容傳送電子郵件。頂層欄位會指定電子郵件的寄件者和收件者。message 欄位包含要傳送的電子郵件詳細資料，包括電子郵件內文。

範例：傳送電子郵件

如要傳送簡單訊息，請將含有 to 欄位和 message 欄位的檔案新增至訊息集合，並包含下列內容：

to: ['[e-mail]'],
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: 寄件者的電子郵件地址。如未在文件中指定，則會使用設定的「預設寄件者地址」參數。
• replyTo：回覆用的電子郵件地址。如未在文件中指定，則會使用設定的「預設回覆地址」參數。
• to：單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
• toUids：包含收件者 UID 的陣列。
• cc：單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
• ccUids：包含副本收件者 UID 的陣列。
• bcc：單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
• bccUids：包含密件副本收件者 UID 的陣列。
• headers：額外標頭欄位的物件 (例如 {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"})。

注意：toUids、ccUids 和 bccUids 選項會根據 Cloud Firestore 文件中與電子郵件地址對應的使用者 UID 傳送電子郵件。如要使用這些收件者選項，您必須為擴充功能的「使用者集合」參數指定 Cloud Firestore 集合。擴充功能隨後會讀取 toUids、ccUids 和/或 bccUids 欄位中指定的每個 UID 的 email 欄位。

訊息欄位

文件的 message 欄位包含電子郵件的原始傳送資訊。一般來說，只有在您自己的伺服器或 Cloud Functions 中執行的受信任程式碼，才應填入這個欄位 (請參閱下方的「安全規則和傳送電子郵件」一節)。

message 欄位的可用屬性如下：

• messageId：電子郵件的郵件 ID 標頭 (如有)。
• subject：電子郵件主旨。
• text：電子郵件的明文內容。
• html：電子郵件的 HTML 內容。
• amp：電子郵件的 AMP4EMAIL 內容。
• attachments：包含附件的陣列；支援 Nodemailer 選項：UTF-8 字串、自訂內容類型、網址、編碼字串、資料 URI 和預先產生的 MIME 節點 (請注意，您的電子郵件無法存取雲端伺服器的檔案系統)。

進階用途

進一步瞭解如何進階使用這項擴充功能：

• 使用 Handlebars 範本搭配「觸發電子郵件」擴充功能
• 使用「觸發電子郵件」擴充功能管理傳送狀態