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:
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.
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
.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ć.
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
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, 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.
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:
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:
- Użyj szablonów kierownicy z rozszerzeniem Trigger Email
- Zarządzaj statusem dostawy dzięki rozszerzeniu Trigger Email