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:
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.
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
.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.
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
ibcc
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.
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:
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:
- Użyj szablonów Handlebars z rozszerzeniem Trigger Email
- Zarządzaj statusem dostawy za pomocą rozszerzenia Trigger Email