使用觸發電子郵件擴展

觸發電子郵件擴展程序 ( 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 交易電子郵件，但它也可以是您自己運行的服務器。

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.',
}

發件人和收件人字段

文檔的頂級字段提供電子郵件發件人和收件人信息。可用的字段是：

• 來自：發件人的電子郵件地址。如果未在文檔中指定，則使用配置的“默認發件人地址”參數。
• replyTo：回復電子郵件地址。如果文檔中未指定，則使用配置的“默認回复地址”參數。
• to：單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
• toUids：包含收件人 UID 的數組。
• cc：單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
• ccUids：包含 CC 收件人 UID 的數組。
• bcc：單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
• bccUids：包含 BCC 收件人 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內容。
• 附件：包含附件的數組；支持的Nodemailer 選項：utf-8 字符串、自定義內容類型、URL、編碼字符串、數據 URI 和預生成的 MIME 節點（請注意，您的電子郵件無法訪問云服務器的文件系統）。

進階使用

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

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