使用触发器电子邮件扩展程序

通过触发器电子邮件扩展程序 (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. 设置外发邮件服务。

   在安装触发器电子邮件扩展程序时，您需要指定 SMTP 服务器的连接和身份验证详细信息，因为扩展程序需要使用此服务器来发送电子邮件。此服务器通常是由电子邮件传送服务提供的，例如 Sendgrid、Mailgun 或 Mailchimp 事务性邮件，但也可以是由您自己运行的服务器。

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

发件人和收件人字段

文档的顶级字段提供电子邮件发件人和收件人信息。可用字段包括：

• from：发件人的电子邮件地址。如果未在文档中指定，则使用配置好的“Default FROM address”参数。
• replyTo：回复电子邮件地址。如果文档中未指定，则使用配置好的“Default REPLY-TO address”参数。
• to：单个收件人电子邮件地址或包含多个收件人电子邮件地址的数组。
• toUids：包含收件人 UID 的数组。
• cc：单个收件人电子邮件地址或包含多个收件人电子邮件地址的数组。
• ccUids：包含 CC 收件人 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 节点（请注意，您的电子邮件无权访问云端服务器的文件系统）。

高级用法

了解此扩展程序的高级用法：

• 将 Handlebars 模板与触发器电子邮件扩展程序搭配使用
• 使用触发器电子邮件扩展程序管理传送状态