Korzystanie z rozszerzenia Trigger Email

Rozszerzenie Trigger Email ( firestore-send-email ) umożliwia automatyczne wysyłanie e-maili na podstawie dokumentów w kolekcji Cloud Firestore. Dodanie dokumentu do kolekcji powoduje, że to rozszerzenie wysyła wiadomość e-mail zbudowaną na podstawie pól dokumentu. Pola najwyższego poziomu dokumentu określają nadawcę i odbiorców wiadomości e-mail, w tym opcje to , cc i bcc (każda obsługuje identyfikatory UID). Pole message dokumentu określa inne elementy wiadomości e-mail, takie jak temat i treść wiadomości e-mail (w postaci zwykłego tekstu lub HTML).

Oto podstawowy przykładowy zapis dokumentu, który uruchomiłby to rozszerzenie:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

Możesz także opcjonalnie skonfigurować to rozszerzenie, aby renderować wiadomości e-mail przy użyciu szablonów Handlebars .

Konfiguracja przed instalacją

Przed zainstalowaniem rozszerzenia wykonaj następujące kroki:

  1. Skonfiguruj usługę poczty wychodzącej.

    Po zainstalowaniu rozszerzenia Trigger Email konieczne będzie określenie szczegółów połączenia i uwierzytelnienia serwera SMTP, którego rozszerzenie używa do wysyłania wiadomości e-mail. Zwykle jest to zapewniane przez usługę dostarczania poczty e-mail, taką jak Sendgrid, Mailgun lub Mailchimp Transactional Email, ale może to być również serwer, który sam uruchamiasz.

  2. Utwórz kolekcję dokumentów e-mailowych.

    Rozszerzenie Trigger Email nasłuchuje nowych dokumentów w określonej kolekcji Cloud Firestore. Gdy znajdzie nowy dokument, rozszerzenie wysyła wiadomość e-mail na podstawie pól dokumentu. W tym celu możesz użyć dowolnej kolekcji Cloud Firestore; przykłady na tej stronie wykorzystują kolekcję o nazwie email .

  3. Skonfiguruj reguły bezpieczeństwa dla kolekcji dokumentów e-mailowych.

    Tego rozszerzenia można używać do wyzwalania dostarczania wiadomości e-mail bezpośrednio z aplikacji klienckich. Należy jednak dokładnie kontrolować dostęp klientów do kolekcji, aby uniknąć potencjalnych nadużyć (nie chcesz, aby użytkownicy mogli wysyłać dowolne e-maile z adresu Twojej firmy!).

    Zasady bezpieczeństwa różnią się w zależności od aplikacji, ale zawsze należy upewnić się, że wiadomości e-mail są wysyłane tylko do zamierzonych odbiorców, a zawartość swobodna jest ograniczona do minimum. Szablony mogą być tutaj pomocne — możesz użyć reguł bezpieczeństwa, aby sprawdzić, czy dane wypełniane w szablonie odpowiadają Twoim oczekiwaniom w zakresie tego, co użytkownik powinien mieć możliwość uruchomienia.

  4. Opcjonalnie: skonfiguruj kolekcję użytkowników.

    W podstawowym użyciu tego rozszerzenia określasz odbiorców wiadomości e-mail, podając ich adresy e-mail w to , cc i bcc dokumentu wiadomości. Alternatywnie, jeśli masz bazę danych użytkowników w Cloud Firestore, możesz określić odbiorców za pomocą identyfikatorów UID użytkowników. Aby to zadziałało, kolekcja użytkowników musi spełniać następujące kryteria:

    • Kolekcja musi być wpisana w identyfikatory użytkowników. Oznacza to, że identyfikator każdego dokumentu użytkownika w kolekcji musi być identyfikatorem UID uwierzytelniania Firebase użytkownika.
    • Każdy dokument użytkownika musi zawierać pole email zawierające adres e-mail użytkownika.

  5. Opcjonalnie: skonfiguruj kolekcję szablonów.

    Możesz renderować wiadomości e-mail za pomocą szablonów Handlebars . Aby to zrobić, będziesz potrzebować kolekcji Cloud Firestore, która będzie zawierać Twoje szablony.

    Aby uzyskać szczegółowe informacje, zobacz Używanie szablonów Handlebars z rozszerzeniem Trigger Email .

Zainstaluj rozszerzenie

Aby zainstalować rozszerzenie, wykonaj czynności opisane na stronie Instalowanie rozszerzenia Firebase . Podsumowując, wykonaj jedną z następujących czynności:

  • Konsola Firebase: Kliknij następujący przycisk:

    Zainstaluj rozszerzenie Trigger Email

  • CLI: Uruchom następujące polecenie:

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

Po zainstalowaniu rozszerzenia zostaniesz poproszony o podanie informacji o połączeniu SMTP i zbiorach Cloud Firestore, które skonfigurowałeś wcześniej.

Użyj rozszerzenia

Po instalacji to rozszerzenie monitoruje wszystkie zapisy dokumentów w skonfigurowanej kolekcji. E-mail jest dostarczany na podstawie zawartości pól dokumentu. Pola najwyższego poziomu określają nadawcę i odbiorców wiadomości e-mail. Pole message zawiera szczegóły wiadomości e-mail do dostarczenia, w tym jej treść.

Przykład: Wyślij e-mail

Aby wysłać prostą wiadomość, dodaj do kolekcji wiadomości dokument z polem to i polem message o następującej treści:

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

Pola nadawcy i odbiorcy

Pola najwyższego poziomu dokumentu zawierają informacje o nadawcy i odbiorcy wiadomości e-mail. Dostępne pola to:

  • od: Adres e-mail nadawcy. Jeżeli nie określono tego w dokumencie, wykorzystuje skonfigurowany parametr „Domyślny adres OD”.
  • AnswerTo: Adres e-mail zwrotny. Jeżeli nie określono tego w dokumencie, wykorzystuje skonfigurowany parametr „Domyślny adres ODPOWIEDZI”.
  • do: pojedynczy adres e-mail odbiorcy lub tablica zawierająca wiele adresów e-mail odbiorców.
  • toUids: Tablica zawierająca identyfikatory UID odbiorców.
  • cc: pojedynczy adres e-mail odbiorcy lub tablica zawierająca wiele adresów e-mail odbiorców.
  • ccUids: Tablica zawierająca identyfikatory UID odbiorców CC.
  • bcc: pojedynczy adres e-mail odbiorcy lub tablica zawierająca wiele adresów e-mail odbiorców.
  • bccUids: Tablica zawierająca identyfikatory UID odbiorców BCC.
  • headers: Obiekt z dodatkowymi polami nagłówka (na przykład {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

UWAGA: Opcje toUids , ccUids i bccUids dostarczają wiadomości e-mail na podstawie identyfikatorów UID użytkowników przypisanych do adresów e-mail w dokumencie Cloud Firestore. Aby skorzystać z tych opcji odbiorców, musisz określić kolekcję Cloud Firestore dla parametru „Kolekcja użytkowników” rozszerzenia. Rozszerzenie może następnie odczytać pole email dla każdego UID określonego w polach toUids , ccUids i/lub bccUids .

Pole wiadomości

Pole message w dokumencie zawiera surowe informacje o dostarczeniu wiadomości e-mail. W zasadzie to pole powinno być wypełniane wyłącznie przez zaufany kod działający na Twoich własnych serwerach lub w Cloud Functions (więcej informacji znajdziesz w sekcji „Zasady bezpieczeństwa i wysyłanie wiadomości e-mail” poniżej).

Dostępne właściwości pola message to:

  • MessageId: Nagłówek identyfikatora wiadomości e-mail, jeśli istnieje.
  • Temat: Temat wiadomości e-mail.
  • tekst: zwykły tekst wiadomości e-mail.
  • html: Treść wiadomości e-mail w formacie HTML.
  • amp: Treść wiadomości e-mail w formacie AMP4EMAIL .
  • załączniki: tablica zawierająca załączniki; Obsługiwane opcje Nodemailera : ciąg utf-8, niestandardowy typ zawartości, adres URL, zakodowany ciąg, identyfikator URI danych i wstępnie wygenerowany węzeł MIME (pamiętaj, że Twój e-mail nie ma dostępu do systemu plików serwera w chmurze).

Zaawansowane użycie

Dowiedz się o bardziej zaawansowanym wykorzystaniu tego rozszerzenia: