Verwendung der Trigger-E-Mail-Erweiterung

Mit der Trigger-E-Mail-Erweiterung ( firestore-send-email ) können Sie automatisch E-Mails basierend auf Dokumenten in einer Cloud Firestore-Sammlung senden. Durch das Hinzufügen eines Dokuments zur Sammlung wird diese Erweiterung dazu veranlasst, eine E-Mail zu senden, die aus den Feldern des Dokuments erstellt wird. Die Felder der obersten Ebene des Dokuments geben den E-Mail-Absender und die E-Mail-Empfänger an, einschließlich der Optionen „ to “, cc “ und bcc “ (die jeweils UIDs unterstützen). Das message des Dokuments gibt die anderen E-Mail-Elemente an, wie Betreffzeile und E-Mail-Text (entweder Klartext oder HTML).

Hier ist ein einfaches Beispiel für das Schreiben eines Dokuments, das diese Erweiterung auslösen würde:

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

Sie können diese Erweiterung optional auch so konfigurieren, dass E-Mails mithilfe von Steering- Vorlagen gerendert werden.

Setup vor der Installation

Führen Sie vor der Installation der Erweiterung die folgenden Schritte aus:

  1. Richten Sie Ihren Postausgangsdienst ein.

    Wenn Sie die Trigger-E-Mail-Erweiterung installieren, müssen Sie die Verbindungs- und Authentifizierungsdetails eines SMTP-Servers angeben, den die Erweiterung zum Senden von E-Mails verwendet. Dies wird normalerweise von einem E-Mail-Zustellungsdienst wie Sendgrid, Mailgun oder Mailchimp Transactional Email bereitgestellt, es könnte sich aber auch um einen Server handeln, den Sie selbst betreiben.

  2. Erstellen Sie eine Sammlung von E-Mail-Dokumenten.

    Die Trigger-E-Mail-Erweiterung wartet auf neue Dokumente in einer von Ihnen angegebenen Cloud Firestore-Sammlung. Wenn ein neues Dokument gefunden wird, sendet die Erweiterung eine E-Mail basierend auf den Feldern des Dokuments. Zu diesem Zweck können Sie jede Cloud Firestore-Sammlung verwenden; Die Beispiele auf dieser Seite verwenden eine Sammlung namens email .

  3. Richten Sie Sicherheitsregeln für Ihre E-Mail-Dokumentensammlung ein.

    Diese Erweiterung kann verwendet werden, um die E-Mail-Zustellung direkt aus Client-Anwendungen auszulösen. Allerdings sollten Sie den Kundenzugriff auf die Sammlung sorgfältig kontrollieren, um potenziellen Missbrauch zu vermeiden (Sie möchten nicht, dass Benutzer beliebige E-Mails von der Adresse Ihres Unternehmens aus senden können!).

    Die Sicherheitsregeln variieren von Anwendung zu Anwendung. Sie sollten jedoch stets darauf achten, dass E-Mails nur an die vorgesehenen Empfänger gesendet werden und frei formulierte Inhalte auf ein Minimum beschränkt werden. Vorlagen können hier hilfreich sein – Sie können Sicherheitsregeln verwenden, um zu überprüfen, ob die in die Vorlage eingefügten Daten Ihren Erwartungen hinsichtlich dessen, was ein Benutzer auslösen darf, entsprechen.

  4. Optional: Richten Sie eine Benutzersammlung ein.

    Bei der grundlegenden Verwendung dieser Erweiterung geben Sie die Empfänger einer E-Mail an, indem Sie deren E-Mail-Adressen in den Feldern „ to , cc “ und „ bcc des Nachrichtendokuments angeben. Wenn Sie über eine Benutzerdatenbank in Cloud Firestore verfügen, können Sie alternativ Empfänger mithilfe der UIDs der Benutzer angeben. Damit dies funktioniert, muss Ihre Benutzersammlung die folgenden Kriterien erfüllen:

    • Die Sammlung muss auf Benutzer-IDs basieren. Das heißt, die Dokument-ID jedes Benutzerdokuments in der Sammlung muss die Firebase-Authentifizierungs-UID des Benutzers sein.
    • Jedes Benutzerdokument muss über ein email Feld verfügen, das die E-Mail-Adresse des Benutzers enthält.
  5. Optional: Richten Sie eine Vorlagensammlung ein.

    Sie können E-Mails mithilfe von Lenkervorlagen rendern. Dazu benötigen Sie eine Cloud Firestore-Sammlung, die Ihre Vorlagen enthält.

    Weitere Informationen finden Sie unter „Verwenden von Lenkervorlagen mit der Trigger-E-Mail-Erweiterung“ .

Installieren Sie die Erweiterung

Um die Erweiterung zu installieren, befolgen Sie die Schritte auf der Seite „Eine Firebase-Erweiterung installieren“ . Zusammenfassend führen Sie einen der folgenden Schritte aus:

Wenn Sie die Erweiterung installieren, werden Sie aufgefordert, Ihre SMTP-Verbindungsinformationen und die Cloud Firestore-Sammlungen anzugeben, die Sie zuvor eingerichtet haben.

Verwenden Sie die Erweiterung

Nach der Installation überwacht diese Erweiterung alle Dokumentschreibvorgänge in der von Ihnen konfigurierten Sammlung. Die E-Mail wird basierend auf dem Inhalt der Felder des Dokuments zugestellt. Die Felder der obersten Ebene geben den Absender und die Empfänger der E-Mail an. Das message enthält die Details der zuzustellenden E-Mail, einschließlich des E-Mail-Texts.

Beispiel: Senden Sie eine E-Mail

Um eine einfache Nachricht zu senden, fügen Sie Ihrer Nachrichtensammlung ein Dokument mit einem to Feld und einem message mit folgendem Inhalt hinzu:

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

Absender- und Empfängerfelder

Die Felder der obersten Ebene des Dokuments liefern die E-Mail-Absender- und Empfängerinformationen. Verfügbare Felder sind:

  • von: Die E-Mail-Adresse des Absenders. Wenn im Dokument nicht angegeben, wird der konfigurierte Parameter „Standard-FROM-Adresse“ verwendet.
  • ReplyTo: Die Antwort-E-Mail-Adresse. Wenn im Dokument nicht angegeben, wird der konfigurierte Parameter „Standard-REPLY-TO-Adresse“ verwendet.
  • an: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • toUids: Ein Array mit den Empfänger-UIDs.
  • cc: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • ccUids: Ein Array mit den CC-Empfänger-UIDs.
  • bcc: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • bccUids: Ein Array mit den BCC-Empfänger-UIDs.
  • Header: Ein Objekt zusätzlicher Header-Felder (zum Beispiel {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

HINWEIS: Die Optionen toUids , ccUids und bccUids stellen E-Mails basierend auf Benutzer-UIDs zu, die mit E-Mail-Adressen in einem Cloud Firestore-Dokument verknüpft sind. Um diese Empfängeroptionen zu verwenden, müssen Sie eine Cloud Firestore-Sammlung für den Parameter „Benutzersammlung“ der Erweiterung angeben. Die Erweiterung kann dann das email Feld für jede in den Feldern toUids , ccUids und/oder bccUids angegebene UID lesen.

Nachrichtenfeld

Das message des Dokuments enthält Rohdaten zur Zustellung der E-Mail. Dieses Feld sollte im Allgemeinen nur von vertrauenswürdigem Code ausgefüllt werden, der auf Ihren eigenen Servern oder Cloud-Funktionen ausgeführt wird (siehe Abschnitt „Sicherheitsregeln und E-Mail-Versand“ weiter unten).

Verfügbare Eigenschaften für das message sind:

  • messageId: Ein Nachrichten-ID-Header für die E-Mail, falls vorhanden.
  • Betreff: Der Betreff der E-Mail.
  • Text: Der Klartextinhalt der E-Mail.
  • html: Der HTML-Inhalt der E-Mail.
  • amp: Der AMP4EMAIL- Inhalt der E-Mail.
  • Anhänge: Ein Array mit Anhängen; Unterstützte Nodemailer-Optionen : UTF-8-Zeichenfolge, benutzerdefinierter Inhaltstyp, URL, codierte Zeichenfolge, Daten-URI und vorgenerierter MIME-Knoten (beachten Sie, dass Ihre E-Mail keinen Zugriff auf das Dateisystem des Cloud-Servers hat).

Erweiterte Verwendung

Erfahren Sie mehr über die erweiterte Verwendung dieser Erweiterung: