Использование расширения 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 этого пользователя.
    • Каждый пользовательский документ должен иметь поле 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.',
}

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

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

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

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

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