Korzystanie z rozszerzenia E-mail z regułą

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

Oto podstawowy przykład zapisu dokumentu, który spowoduje uruchomienie tego rozszerzenia:

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

Opcjonalnie możesz też skonfigurować to rozszerzenie tak, aby renderowało e-maile za pomocą szablonów Handlebars.

Konfiguracja przed instalacją

Przed zainstalowaniem rozszerzenia wykonaj te czynności:

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

    Podczas instalowania rozszerzenia Trigger Email musisz podać szczegóły połączenia i uwierzytelniania serwera SMTP, którego rozszerzenie używa do wysyłania e-maili. Zwykle jest to usługa dostarczania e-maili, np. Sendgrid, Mailgun lub Mailchimp Transactional Email, ale może to być też serwer, który sam obsługujesz.

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

    Rozszerzenie Wyślij e-maila po wywołaniu reguły nasłuchuje nowych dokumentów w Cloud Firestoreokreślonej przez Ciebie kolekcji. Gdy znajdzie nowy dokument, rozszerzenie wyśle e-maila na podstawie pól dokumentu. W tym celu możesz użyć dowolnej kolekcji Cloud Firestore. Przykłady na tej stronie korzystają z kolekcji o nazwie email.

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

    To rozszerzenie może służyć do wywoływania dostarczania e-maili bezpośrednio z aplikacji klienckich. Musisz 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 zabezpieczeń będą się różnić w zależności od aplikacji, ale zawsze należy dbać o to, aby e-maile były wysyłane tylko do zamierzonych odbiorców, a treści w formie swobodnej były ograniczone do minimum. Pomocne mogą być tutaj szablony. Za pomocą reguł zabezpieczeń możesz sprawdzić, czy dane wypełniające szablon są zgodne z Twoimi oczekiwaniami co do tego, co użytkownik powinien mieć możliwość wywołać.

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

    W przypadku podstawowego użycia tego rozszerzenia odbiorców e-maila określa się, wpisując ich adresy e-mail w polach to, cc i bcc dokumentu wiadomości. 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 ta funkcja działała, kolekcja użytkowników musi spełniać te kryteria:

    • Kolekcja musi być kluczowana na podstawie identyfikatorów użytkowników. Oznacza to, że identyfikator dokumentu każdego dokumentu użytkownika w kolekcji musi być identyfikatorem Firebase Authentication UID użytkownika.
    • Każdy dokument użytkownika musi zawierać pole email z adresem e-mail użytkownika.

  5. Opcjonalnie: skonfiguruj kolekcję szablonów.

    E-maile możesz renderować za pomocą szablonów Handlebars. W tym celu musisz mieć kolekcję Cloud Firestore, w której będą przechowywane Twoje szablony.

    Więcej informacji znajdziesz w artykule Używanie szablonów Handlebars z rozszerzeniem Trigger Email.

Instalowanie rozszerzenia

Aby zainstalować rozszerzenie, wykonaj czynności opisane na stronie Instalowanie Firebase Extension. Podsumowując, wykonaj jedną z tych czynności:

  • Firebase konsola: kliknij ten przycisk:

    Instalowanie rozszerzenia Trigger Email

  • Interfejs CLI: uruchom to polecenie: 

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

Podczas instalowania rozszerzenia pojawi się prośba o podanie informacji o połączeniu SMTP i Cloud Firestore kolekcji skonfigurowanych wcześniej.

Korzystanie z rozszerzenia

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

Przykład: wysyłanie e-maila

Aby wysłać prostą wiadomość, dodaj do kolekcji wiadomości dokument z polem to i polem message o tej 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 e-maila. Dostępne pola:

  • from: adres e-mail nadawcy; Jeśli nie został określony w dokumencie, używa skonfigurowanego parametru „Domyślny adres NAD”.
  • replyTo: adres e-mail do przesłania odpowiedzi. Jeśli nie został określony w dokumencie, używa skonfigurowanego parametru „Domyślny adres ODPOWIEDZI”.
  • to: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 w polu DW.
  • 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 w polu UDW.
  • headers: obiekt dodatkowych pól nagłówka (np. {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

UWAGA: opcje toUids, ccUids i bccUids wysyłają e-maile na podstawie identyfikatorów użytkowników powiązanych z adresami e-mail w dokumencie Cloud Firestore. Aby korzystać z tych opcji odbiorców, musisz określić kolekcję Cloud Firestore dla parametru „Kolekcja użytkowników” rozszerzenia. Rozszerzenie może wtedy odczytać pole email dla każdego identyfikatora UID określonego w polach toUids, ccUids lub bccUids.

Pole wiadomości

Pole message dokumentu zawiera nieprzetworzone informacje o dostarczeniu e-maila. To pole powinno być wypełniane tylko przez zaufany kod działający na Twoich serwerach lub w Cloud Functions (patrz sekcja „Reguły zabezpieczeń i wysyłanie e-maili” poniżej).

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

  • messageId: nagłówek identyfikatora wiadomości w e-mailu (jeśli występuje).
  • subject: temat e-maila.
  • text: treść e-maila w formacie zwykłego tekstu.
  • html: treść e-maila w formacie HTML.
  • amp: treść e-maila w formacie AMP4EMAIL.
  • attachments: tablica zawierająca załączniki; obsługiwane opcje Nodemailer: ciąg znaków UTF-8, niestandardowy typ treści, adres URL, zakodowany ciąg znaków, identyfikator URI danych i węzeł MIME wygenerowany wcześniej (pamiętaj, że Twój e-mail nie ma dostępu do systemu plików serwera w chmurze).

Do wymagających zadań

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