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 rozszerzenie to wyśle ​​wiadomość e-mail utworzoną 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 wiersz tematu i treść wiadomości e-mail (w postaci zwykłego tekstu lub HTML).

Oto podstawowy przykładowy zapis dokumentu, który uruchomi 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 również 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 czynności:

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

    Podczas instalowania rozszerzenia Trigger Email należy określić szczegóły połączenia i uwierzytelniania serwera SMTP, którego rozszerzenie używa do wysyłania wiadomości e-mail. Jest to zwykle 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 prowadzisz.

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

    Rozszerzenie Trigger Email nasłuchuje nowych dokumentów w określonej przez Ciebie 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 używają kolekcji o nazwie email .

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

    To rozszerzenie może służyć 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!).

    Reguły bezpieczeństwa będą się różnić w zależności od aplikacji, ale należy zawsze upewnić się, że wiadomości e-mail są wysyłane tylko do zamierzonych odbiorców, a treść w dowolnej formie jest ograniczona do minimum. Szablony mogą w tym pomóc — możesz użyć reguł zabezpieczeń, aby zweryfikować, czy dane wypełniane w szablonie odpowiadają Twoim oczekiwaniom dotyczącym tego, co użytkownik powinien aktywować.

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

    W podstawowym użyciu tego rozszerzenia określasz odbiorców wiadomości e-mail, określając ich adresy e-mail w polach 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, Twoja 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 użytkownika Firebase Authentication.
    • Każdy dokument użytkownika musi mieć pole email zawierające adres e-mail użytkownika.

  5. Opcjonalnie: skonfiguruj kolekcję szablonów.

    Możesz renderować e-maile za pomocą szablonów Handlebars . Aby to zrobić, potrzebujesz kolekcji Cloud Firestore, która będzie zawierać Twoje szablony.

    Aby uzyskać szczegółowe informacje, zobacz Używanie szablonów kierownic 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

Podczas instalowania rozszerzenia zostanie wyświetlony monit o podanie informacji o połączeniu SMTP oraz skonfigurowanych wcześniej kolekcji Cloud Firestore.

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 treść wiadomości e-mail.

Przykład: Wyślij e-mail

Aby wysłać prostą wiadomość, dodaj dokument do swojej kolekcji wiadomości 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śli nie określono w dokumencie, używa skonfigurowanego parametru „Domyślny adres OD”.
  • Odpowiedz na: adres e-mail odpowiedzi. Jeśli nie jest określony w dokumencie, używa skonfigurowanego parametru „Domyślny adres ODPOWIEDZI DO”.
  • 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.
  • UDW: pojedynczy adres e-mail odbiorcy lub tablica zawierająca wiele adresów e-mail odbiorców.
  • bccUids: tablica zawierająca identyfikatory UID odbiorców UDW.
  • nagłówki: obiekt z dodatkowymi polami nagłówka (na przykład {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

UWAGA: 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 adresatów, musisz określić kolekcję Cloud Firestore dla parametru rozszerzenia „Kolekcja Użytkownicy”. Rozszerzenie może następnie odczytać pole email dla każdego identyfikatora UID określonego w toUids , ccUids i/lub bccUids .

Pole wiadomości

Pole message w dokumencie zawiera surowe informacje o dostarczeniu wiadomości e-mail. To pole powinno być wypełniane tylko przez zaufany kod działający na Twoich własnych serwerach lub w Cloud Functions (zobacz sekcję „Reguły 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: treść wiadomości e-mail w postaci zwykłego tekstu.
  • html: zawartość HTML wiadomości e-mail.
  • amp: zawartość AMP4EMAIL wiadomości e-mail.
  • załączniki: tablica zawierająca załącznik(i); Obsługiwane opcje Nodemailera : ciąg utf-8, niestandardowy typ treś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 zastosowanie

Dowiedz się więcej o bardziej zaawansowanym korzystaniu z tego rozszerzenia: