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

您可以使用「觸發電子郵件」擴充功能 (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 Transactional Email，但也可以是您自行執行的伺服器。

  2. 建立電子郵件文件集合。

    觸發電子郵件擴充功能會監聽您指定的 Cloud Firestore 集合中是否有新文件。當擴充功能找到新文件時，就會根據文件的欄位傳送電子郵件。您可以使用任何 Cloud Firestore 集合來達成這個目的；本頁範例使用名為 email 的集合。

  3. 針對收集電子郵件文件設定安全性規則。

    這個擴充功能可用於直接從用戶端應用程式觸發電子郵件傳送作業。不過，您應謹慎控管客戶對集合的存取權，以免遭到濫用 (您不希望使用者能以貴公司的地址隨意傳送電子郵件)。

    安全性規則會因應用程式而異，但您應一律確保電子郵件只傳送給預期收件者，並盡可能減少自由格式內容。範本可協助您達成此目標。您可以使用安全性規則，驗證填入範本的資料是否符合預期使用者能觸發作業的預期。

  4. 選用：設定使用者集合。

    在這項擴充功能的基本用法下，如要指定電子郵件收件者，請在訊息文件的 to、cc 和 bcc 欄位中指定他們的電子郵件地址。或者，如果您在 Cloud Firestore 中擁有使用者資料庫，可以使用使用者的 UID 指定收件者。為確保這項功能正常運作，您的使用者集合必須符合下列條件：

    • 集合必須以使用者 ID 做為索引鍵。也就是說，集合中每個使用者文件的文件 ID 都必須是使用者的 Firebase Authentication UID。
    • 每份使用者文件都必須有 email 欄位，其中包含使用者的電子郵件地址。

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

    您可以使用 Handlebars 範本呈現電子郵件。如要這麼做，您需要一個 Cloud Firestore 集合來容納範本。

    詳情請參閱「使用觸發電子郵件外掛程式搭配 Handlebars 範本」。

安裝擴充功能

如要安裝擴充功能，請按照「安裝 Firebase Extension」頁面上的步驟操作。總結來說，請採取下列任一做法：

  • 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: 寄件者的電子郵件地址。如果未在文件中指定，則使用設定的「Default FROM address」參數。
  • replyTo: 回覆用的電子郵件地址。如果文件中未指定，則會使用已設定的「Default REPLY-TO address」參數。
  • to: 單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
  • toUids：包含收件者 UID 的陣列。
  • cc: 單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
  • ccUids：包含副本收件者 UID 的陣列。
  • 密件副本：單一收件者電子郵件地址或包含多個收件者電子郵件地址的陣列。
  • 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 節點 (請注意，您的電子郵件無法存取雲端伺服器的檔案系統)。

進階用途

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