使用觸發電子郵件擴展

觸發電子郵件擴展 ( 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. 設置您的外發郵件服務。

   安裝觸發電子郵件擴展程序時，您需要指定擴展程序用於發送電子郵件的 SMTP 服務器的連接和身份驗證詳細信息。這通常由電子郵件傳送服務（例如 Sendgrid、Mailgun 或 Mailchimp 事務電子郵件）提供，但它也可能是您自己運行的服務器。

2. 創建電子郵件文檔集合。

   觸發電子郵件擴展程序會偵聽您指定的 Cloud Firestore 集合中的新文檔。當找到新文檔時，擴展程序會根據文檔的字段發送一封電子郵件。您可以使用任何 Cloud Firestore 集合來實現此目的；此頁面上的示例使用名為email的集合。

3. 為您的電子郵件文檔集合設置安全規則。

   此擴展可用於直接從客戶端應用程序觸發電子郵件傳送。但是，您應該仔細控制客戶端對集合的訪問，以避免潛在的濫用（您不希望用戶能夠從您公司的地址發送任意電子郵件！）。

   安全規則因應用程序而異，但您應始終確保電子郵件僅發送給預期收件人，並將自由格式內容保持在最低限度。模板可以在這方面提供幫助 - 您可以使用安全規則來驗證填充到模板的數據是否符合您對允許用戶觸發的期望。

4. 可選：設置用戶集合。

   在此擴展的基本用法下，您可以通過在消息文檔的to 、 cc和bcc字段中指定電子郵件地址來指定電子郵件的收件人。或者，如果您在 Cloud Firestore 中有用戶數據庫，則可以使用用戶的 UID 指定收件人。為此，您的用戶集合必須滿足以下條件：

   • 該集合必須以用戶 ID 為關鍵字。也就是說，集合中每個用戶文檔的文檔 ID 必須是用戶的 Firebase 身份驗證 UID。
   • 每個用戶文檔必須有一個包含用戶電子郵件地址的email字段。

5. 可選：設置模板集合。

   您可以使用Handlebars 模板呈現電子郵件。為此，您需要一個 Cloud Firestore 集合來包含您的模板。

   有關詳細信息，請參閱將 Handlebars 模板與觸發電子郵件擴展一起使用。

安裝擴展

要安裝該擴展，請按照安裝 Firebase 擴展頁面上的步驟操作。總之，請執行以下操作之一：

• Firebase 控制台：單擊以下按鈕：

  安裝觸發電子郵件擴展

• 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：發件人的電子郵件地址。如果文檔中未指定，則使用配置的“默認發件人地址”參數。
• replyTo：回復電子郵件地址。如果文檔中未指定，則使用配置的“默認 REPLY-TO 地址”參數。
• to：單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
• toUids：包含收件人 UID 的數組。
• 抄送：單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
• ccUids：包含 CC 收件人 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字段包含電子郵件的原始傳遞信息。此字段通常應僅由在您自己的服務器或云功能中運行的受信任代碼填充（請參閱下面的“安全規則和發送電子郵件”部分）。

message字段的可用屬性有：

• messageId：電子郵件的消息 ID 標頭（如果有）。
• 主題：電子郵件的主題。
• text：電子郵件的明文內容。
• html：電子郵件的 HTML 內容。
• amp：電子郵件的AMP4EMAIL內容。
• Attachments：包含附件的數組；支持的Nodemailer 選項：utf-8 字符串、自定義內容類型、URL、編碼字符串、數據 URI 和預生成的 MIME 節點（請注意，您的電子郵件無法訪問云服務器的文件系統）。

高級使用

了解此擴展的更高級用法：

• 將 Handlebars 模板與 Trigger Email 擴展一起使用
• 使用觸發電子郵件擴展管理傳遞狀態