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

您可以使用「觸發電子郵件」擴充功能 (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 主控台：按一下下列按鈕：

    安裝「Trigger Email」擴充功能

  • 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: 回覆用的電子郵件地址。如果文件中未指定，則會使用已設定的「Default REPLY-TO address」參數。
  • to: 單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
  • toUids：包含收件者 UID 的陣列。
  • cc: 單一收件者電子郵件地址，或包含多個收件者電子郵件地址的陣列。
  • ccUids：包含副本收件人 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 欄位包含電子郵件的原始傳送資訊。這個欄位通常只應填入在您自己的伺服器或 Cloud Functions 中執行的受信任程式碼 (請參閱下方的「安全性規則和傳送電子郵件」一節)。

message 欄位可用的屬性如下：

  • messageId：電子郵件的郵件 ID 標頭 (如有)。
  • subject：電子郵件主旨。
  • text：電子郵件的明文內容。
  • html：電子郵件的 HTML 內容。
  • amp：電子郵件的 AMP4EMAIL 內容。
  • attachments: 包含附件的陣列；支援的 Nodemailer 選項：utf-8 字串、自訂內容類型、網址、經過編碼的字串、資料 URI 和預先產生的 MIME 節點 (請注意，您的電子郵件無法存取雲端伺服器的檔案系統)。

進階用途

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