Использование расширения триггерной электронной почты

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

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

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

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

   Дополнительные сведения см. в разделе Использование шаблонов Handlebars с расширением Trigger Email .

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

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

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

  Установите расширение триггерной электронной почты

• CLI: выполните следующую команду:

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

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

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

• from: адрес электронной почты отправителя. Если не указано в документе, использует настроенный параметр «Адрес отправителя по умолчанию».
• answerTo: адрес электронной почты для ответа. Если не указано в документе, использует настроенный параметр «Адрес ОТВЕТА ПО УМОЛЧАНИЮ».
• to: адрес электронной почты одного получателя или массив, содержащий адреса электронной почты нескольких получателей.
• toUids: массив, содержащий UID получателей.
• копия: один адрес электронной почты получателя или массив, содержащий несколько адресов электронной почты получателя.
• ccUids: массив, содержащий UID получателей CC.
• скрытая копия: адрес электронной почты одного получателя или массив, содержащий несколько адресов электронной почты получателя.
• bccUids: массив, содержащий UID получателей скрытой копии.
• заголовки: объект дополнительных полей заголовка (например, {"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: заголовок идентификатора сообщения электронной почты, если он есть.
• Subject: Тема письма.
• текст: открытый текст сообщения электронной почты.
• html: HTML-контент электронной почты.
• amp: содержимое письма AMP4EMAIL .
• вложения: массив, содержащий вложения; Поддерживаемые параметры Nodemailer : строка utf-8, настраиваемый тип содержимого, URL-адрес, закодированная строка, URI данных и предварительно созданный узел MIME (помните, что ваша электронная почта не имеет доступа к файловой системе облачного сервера).

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

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

• Используйте шаблоны Handlebars с расширением Trigger Email
• Управляйте статусом доставки с помощью расширения Trigger Email