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

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

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

  2. 创建电子邮件文档集合。

    触发器电子邮件扩展程序会监听您指定的 Cloud Firestore 集合中的新文档。如果发现新文档,扩展程序会根据该文档的字段发送电子邮件。为此,您可以使用任何 Cloud Firestore 集合;本页面上的示例使用一个名为 email 的集合。

  3. 为电子邮件文档集合设置安全规则。

    此扩展程序可用于直接从客户端应用触发电子邮件传送。不过您应该谨慎控制客户端对该集合的访问权限,避免可能出现的滥用问题(您必定不会希望用户能通过公司的电子邮件地址随意乱发电子邮件!)。

    安全规则对于不同的应用有所不同,但您应该始终确保电子邮件仅发送给预期收件人,并尽可能减少自由格式的内容。在这种情况下,模板就可以帮上忙 - 您可以使用安全规则来验证填充到模板中的数据,确认其是否符合您针对应该允许用户触发的操作的预期。

  4. 可选:设置用户集合。

    根据此扩展程序的基本用法,若要指定电子邮件的收件人,在邮件文档的 toccbcc 字段中指定收件人的电子邮件地址即可。或者,如果您在 Cloud Firestore 中有用户数据库,也可以通过用户的 UID 来指定收件人。要使用这种方法,您的用户集合必须满足以下条件:

    • 该集合必须以用户 ID 作为键。也就是说,集合中每个用户文档的文档 ID 都必须是用户的 Firebase Authentication UID。
    • 每个用户文档都必须有一个 email 字段,其中包含用户的电子邮件地址。
  5. 可选:设置模板集合。

    您可以使用 Handlebars 模板呈现电子邮件。 为此,您需要一个 Cloud Firestore 集合来包含模板。

    如需了解详情,请参阅将 Handlebars 模板与触发器电子邮件扩展程序结合使用

安装扩展程序

要安装该扩展程序,请按照安装 Firebase Extensions 页面上的步骤操作。总的来说,请执行以下任一操作:

安装扩展程序时,系统会提示您指定 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:包含 CC 收件人 UID 的数组。
  • bcc:单个收件人电子邮件地址或包含多个收件人电子邮件地址的数组。
  • bccUids:包含密送收件人 UID 的数组。
  • headers:其他标题字段的对象(例如 {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"})。

注意toUidsccUidsbccUids 选项可以将电子邮件传送到 Cloud Firestore 文档中以用户 UID 作为键的电子邮件地址中。要使用这些收件人选项,您需要为此扩展程序的“用户集合”参数指定一个 Cloud Firestore 集合。然后,此扩展程序可以读取 toUidsccUids 和/或 bccUids 字段中指定的每个 UID 的 email 字段。

邮件字段

文档的 message 字段包含电子邮件的原始递送信息。此字段通常应仅由在您自己的服务器或 Cloud Functions 中运行的可信代码填充(请参阅下面的“安全规则和发送电子邮件”部分)。

message 字段的可用属性包括:

  • messageId:电子邮件的邮件 ID 标题(如果有)。
  • subject:电子邮件的主题。
  • text:电子邮件的纯文本内容。
  • html:电子邮件的 HTML 内容。
  • amp:电子邮件的 AMP4EMAIL 内容。
  • attachments:含有附件的数组;支持的 Nodemailer 选项:utf-8 字符串、自定义内容类型、网址、编码字符串、数据 URI 和预先生成的 MIME 节点(请注意,您的电子邮件无权访问云端服务器的文件系统)。

高级用法

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