使用触发电子邮件扩展

触发电子邮件扩展程序 ( firestore-send-email ) 可让您根据 Cloud Firestore 集合中的文档自动发送电子邮件。将文档添加到集合会触发此扩展程序发送根据文档字段构建的电子邮件。文档的顶级字段指定电子邮件发件人和收件人，包括to 、 cc和bcc选项（每个都支持 UID）。文档的message字段指定其他电子邮件元素，如主题行和电子邮件正文（纯文本或 HTML）。

这是将触发此扩展的基本示例文档编写：

admin.firestore().collection('mail').add({
  to: '[e-mail]',
  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: ['[e-mail]'],
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 扩展一起使用
• 使用触发电子邮件扩展管理交付状态