Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

使用觸發電子郵件擴展

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

觸發電子郵件擴展程序 ( firestore-send-email ) 可讓您根據 Cloud Firestore 集合中的文檔自動發送電子郵件。將文檔添加到集合會觸發此擴展程序以發送根據文檔字段構建的電子郵件。文檔的頂級字段指定電子郵件發件人和收件人,包括toccbcc選項(每個都支持 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. 創建電子郵件文檔集合。

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

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

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

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

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

    在此擴展的基本用法下,您可以通過在消息文檔的toccbcc字段中指定他們的電子郵件地址來指定電子郵件的收件人。作為替代方案,如果您在 Cloud Firestore 中有用戶數據庫,則可以使用用戶的 UID 指定收件人。為此,您的用戶集合必須滿足以下條件:

    • 集合必須鍵入用戶 ID。即集合中每個用戶文檔的文檔 ID 必須是用戶的 Firebase 身份驗證 UID。
    • 每個用戶文檔都必須有一個包含用戶電子郵件地址的email字段。
  5. 可選:設置模板集合。

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

    有關詳細信息,請參閱將 Handlebars 模板與 Trigger Email 擴展一起使用。

安裝擴展

要安裝擴展程序,請按照安裝 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:發件人的電子郵件地址。如果文檔中未指定,則使用配置的“默認 FROM 地址”參數。
  • replyTo:回復電子郵件地址。如果文檔中未指定,則使用配置的“默認回复地址”參數。
  • to:單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
  • toUids:包含收件人 UID 的數組。
  • cc:單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
  • ccUids:包含抄送收件人 UID 的數組。
  • bcc:單個收件人電子郵件地址或包含多個收件人電子郵件地址的數組。
  • bccUids:包含密件抄送收件人 UID 的數組。
  • headers:附加標頭字段的對象(例如{"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} )。

注意: toUidsccUidsbccUids選項根據用戶 UID 發送電子郵件,該用戶 UID 鍵入 Cloud Firestore 文檔中的電子郵件地址。要使用這些收件人選項,您需要為擴展程序的“用戶集合”參數指定 Cloud Firestore 集合。然後,擴展程序可以讀取在toUidsccUids和/或bccUids字段中指定的每個 UID 的email字段。

留言區

文檔的message字段包含電子郵件的原始傳遞信息。此字段通常只能由運行在您自己的服務器或 Cloud Functions 中的受信任代碼填充(請參閱下面的“安全規則和發送電子郵件”部分)。

message字段的可用屬性有:

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

高級使用

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