Использование расширения 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 пользователей. Чтобы это работало, ваша коллекция пользователей должна соответствовать следующим критериям:

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

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

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

    Подробную информацию см. в разделе Использование шаблонов Handlebars с расширением Trigger Email .

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

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

При установке расширения вам будет предложено указать данные вашего 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: Адрес электронной почты отправителя. Если не указано в документе, используется настроенный параметр "Адрес FROM по умолчанию".
  • replyTo: Адрес электронной почты для ответа. Если не указано в документе, используется настроенный параметр "Адрес по умолчанию для ответа".
  • кому: Один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • toUids: Массив, содержащий UID получателей.
  • cc: один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • ccUids: массив, содержащий UID получателей CC.
  • bcc: один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателей.
  • bccUids: массив, содержащий UID получателей BCC.
  • заголовки: объект дополнительных полей заголовка (например, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

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

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

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

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

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

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

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