Использование расширения Trigger Email

Расширение Trigger Email ( 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. Настройте службу исходящей почты.

    При установке расширения Trigger Email вам потребуется указать данные для подключения и аутентификации SMTP-сервера, который расширение использует для отправки электронных писем. Обычно это предоставляется службой доставки почты, такой как Sendgrid, Mailgun или Mailchimp Transactional Email, но это также может быть сервер, который вы используете самостоятельно.

  2. Создайте коллекцию электронных писем.

    Расширение Trigger Email отслеживает появление новых документов в указанной вами коллекции Cloud Firestore . При обнаружении нового документа расширение отправляет электронное письмо на основе полей документа. Для этой цели можно использовать любую коллекцию Cloud Firestore ; в примерах на этой странице используется коллекция с именем email .

  3. Настройте правила безопасности для вашей коллекции электронных писем.

    Это расширение можно использовать для запуска отправки электронных писем непосредственно из клиентских приложений. Однако следует тщательно контролировать доступ клиентов к коллекции, чтобы избежать потенциальных злоупотреблений (вы же не хотите, чтобы пользователи могли отправлять произвольные электронные письма с адреса вашей компании!).

    Правила безопасности различаются в зависимости от приложения, но всегда следует убедиться, что электронные письма отправляются только предполагаемым получателям, а объем произвольного контента сведен к минимуму. В этом могут помочь шаблоны — вы можете использовать правила безопасности, чтобы проверить, соответствуют ли данные, заполняемые в шаблон, вашим ожиданиям относительно того, что пользователь должен иметь право активировать.

  4. Необязательно: Настройте коллекцию пользователей.

    При базовом использовании этого расширения вы указываете получателей электронного письма, указывая их адреса электронной почты в полях to , cc и bcc документа сообщения. В качестве альтернативы, если у вас есть база данных пользователей в Cloud Firestore , вы можете указать получателей, используя UID пользователей. Для этого ваша коллекция пользователей должна соответствовать следующим критериям:

    • Коллекция должна быть основана на идентификаторах пользователей. То есть идентификатор документа каждого пользовательского документа в коллекции должен совпадать с UID пользователя Firebase Authentication .
    • В каждом документе пользователя должно быть поле для ввода адреса email почты пользователя.

  5. Необязательно: создайте коллекцию шаблонов.

    Вы можете создавать электронные письма, используя шаблоны Handlebars . Для этого вам понадобится коллекция Cloud Firestore для хранения ваших шаблонов.

    Подробности см. в разделе «Использование шаблонов Handlebars с расширением Trigger Email» .

Установите расширение

Для установки расширения следуйте инструкциям на странице «Установка Firebase Extension . Вкратце, выполните одно из следующих действий:

  • Консоль Firebase : Нажмите следующую кнопку:

    Установите расширение Trigger Email.

  • Интерфейс командной строки: Выполните следующую команду:

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

Поля отправителя и получателя

Поля верхнего уровня документа содержат информацию об отправителе и получателе электронного письма. Доступные поля:

  • От: Адрес электронной почты отправителя. Если не указан в документе, используется настроенный параметр "Адрес отправителя по умолчанию".
  • replyTo: Адрес электронной почты для ответа. Если не указан в документе, используется настроенный параметр "Адрес для ответа по умолчанию".
  • Кому: Один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • toUids: Массив, содержащий UID получателей.
  • cc: Один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • ccUids: Массив, содержащий UID получателей копии письма.
  • bcc: Один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • bccUids: Массив, содержащий UID получателей BCC.
  • headers: Объект, содержащий дополнительные поля заголовка (например, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

ПРИМЕЧАНИЕ: Параметры toUids , ccUids и bccUids позволяют отправлять электронные письма на основе UID пользователей, привязанных к адресам электронной почты в документе Cloud Firestore. Для использования этих параметров получателей необходимо указать коллекцию Cloud Firestore для параметра "Коллекция пользователей" расширения. Затем расширение сможет считывать поле email для каждого UID, указанного в полях toUids , ccUids и/или bccUids .

Поле сообщения

Поле message документа содержит исходные данные для доставки электронного письма. Как правило, это поле следует заполнять только доверенным кодом, работающим на ваших собственных серверах или в облачных функциях (см. раздел «Правила безопасности и отправка электронной почты» ниже).

Для поля message доступны следующие свойства:

  • messageId: Заголовок с идентификатором сообщения в электронном письме, если таковой имеется.
  • Тема: Тема электронного письма.
  • текст: текстовое содержимое электронного письма.
  • html: HTML-содержимое электронного письма.
  • amp: Содержимое электронного письма, полученное с помощью AMP4EMAIL .
  • Вложения: Массив, содержащий вложения; Поддерживаемые параметры Nodemailer : строка utf-8, пользовательский тип контента, URL, закодированная строка, URI данных и предварительно сгенерированный MIME-узел (обратите внимание, что ваша электронная почта не имеет доступа к файловой системе облачного сервера).

Расширенное использование

Узнайте о более продвинутых способах использования этого расширения: