使用觸發電子郵件擴展

觸發電子郵件擴充功能 ( 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 節點（請注意，您的電子郵件無法存取雲端伺服器的檔案系統）。

進階使用

了解此擴充功能的更進階用法：