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

  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 . Вкратце, выполните одно из следующих действий:

При установке расширения вам будет предложено указать информацию о вашем 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: адрес электронной почты отправителя. Если не указано в документе, используется настроенный параметр «Адрес отправителя по умолчанию».
  • ReplyTo: адрес электронной почты для ответа. Если не указано в документе, используется настроенный параметр «Адрес ответа по умолчанию».
  • to: адрес электронной почты одного получателя или массив, содержащий адреса электронной почты нескольких получателей.
  • toUids: массив, содержащий UID получателя.
  • cc: адрес электронной почты одного получателя или массив, содержащий адреса электронной почты нескольких получателей.
  • ccUids: массив, содержащий UID получателей CC.
  • Скрытая копия: адрес электронной почты одного получателя или массив, содержащий несколько адресов электронной почты получателей.
  • 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 (имейте в виду, что ваша электронная почта не имеет доступа к файловой системе облачного сервера).

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

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