Trigger-E-Mail-Erweiterung verwenden

Mit der Erweiterung „Trigger-E-Mail“ (firestore-send-email) können Sie automatisch E-Mails basierend auf Dokumenten in einer Cloud Firestore-Sammlung senden. Wenn Sie der Sammlung ein Dokument hinzufügen, sendet diese Erweiterung eine E-Mail, die aus den Feldern des Dokuments erstellt wurde. In den Feldern der obersten Ebene des Dokuments werden der E-Mail-Absender und die E-Mail-Empfänger angegeben, einschließlich der Optionen to, cc und bcc (alle mit Unterstützung von UIDs). Im Feld message des Dokuments werden die anderen E-Mail-Elemente wie Betreffzeile und E-Mail-Text (entweder Nur-Text oder HTML) angegeben.

Hier ein einfaches Beispiel für eine Dokumenterstellung, die diese Erweiterung auslöst:

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

Optional kannst du diese Erweiterung auch so konfigurieren, dass E-Mails mithilfe von Handlebars-Vorlagen gerendert werden.

Einrichtung vor der Installation

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

  1. Richten Sie den Dienst für ausgehende E-Mails ein.

    Wenn Sie die Trigger-E-Mail-Erweiterung installieren, müssen Sie die Verbindungs- und Authentifizierungsdetails eines SMTP-Servers angeben, über den die Erweiterung E-Mails sendet. Diese wird in der Regel von einem E-Mail-Bereitstellungsdienst wie Sendgrid, Mailgun oder Mailchimp Transaktions-E-Mail bereitgestellt. Es kann sich aber auch um einen selbst ausgeführten Server handeln.

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

    Die Erweiterung „Trigger-E-Mail“ überwacht neue Dokumente in einer von Ihnen angegebenen Cloud FirestoreSammlung. Wenn die Erweiterung ein neues Dokument findet, sendet sie eine E-Mail anhand der Felder des Dokuments. Sie können dazu eine beliebige Cloud Firestore-Sammlung verwenden. In den Beispielen auf dieser Seite wird eine Sammlung namens email verwendet.

  3. Legen Sie Sicherheitsregeln für die Sammlung von E-Mail-Dokumenten fest.

    Mit dieser Erweiterung können Sie die E‑Mail-Zustellung direkt über Clientanwendungen auslösen. Sie sollten den Zugriff von Kunden auf die Sammlung jedoch sorgfältig steuern, um möglichen Missbrauch zu vermeiden. Nutzer sollten nicht in der Lage sein, beliebige E-Mails von der Adresse Ihres Unternehmens zu senden.

    Die Sicherheitsregeln variieren je nach Anwendung. Sie sollten jedoch immer darauf achten, dass E-Mails nur an die vorgesehenen Empfänger gesendet werden und dass Inhalte in Form freier Texte auf ein Minimum beschränkt werden. Vorlagen können hier hilfreich sein. Mithilfe von Sicherheitsregeln können Sie prüfen, ob die Daten, die in die Vorlage eingefügt werden, Ihren Erwartungen entsprechen, was ein Nutzer auslösen darf.

  4. Optional: Richten Sie eine Sammlung „Nutzer“ ein.

    Bei der grundlegenden Verwendung dieser Erweiterung geben Sie die Empfänger einer E-Mail an, indem Sie ihre E-Mail-Adressen in den Feldern to, cc und bcc des Nachrichtendokuments angeben. Wenn Sie eine Nutzerdatenbank in Cloud Firestore haben, können Sie alternativ Empfänger anhand der UIDs der Nutzer angeben. Dazu muss Ihre Nutzersammlung die folgenden Kriterien erfüllen:

    • Die Sammlung muss auf Nutzer-IDs basieren. Das bedeutet, dass die Dokument-ID jedes Nutzerdokuments in der Sammlung die Firebase Authentication-UID des Nutzers sein muss.
    • Jedes Nutzerdokument muss das Feld email haben, das die E-Mail-Adresse des Nutzers enthält.

  5. Optional: Richten Sie eine Vorlagensammlung ein.

    Du kannst E-Mails mit Handlebars-Vorlagen rendern. Dazu benötigen Sie eine Cloud Firestore-Sammlung, die Ihre Vorlagen enthält.

    Weitere Informationen finden Sie unter Handlebars-Vorlagen mit der Trigger-E-Mail-Erweiterung verwenden.

Erweiterung installieren

Folgen Sie der Anleitung auf der Seite Firebase Extension installieren, um die Erweiterung zu installieren. Sie haben folgende Möglichkeiten:

  • Firebase Console: Klicken Sie auf die folgende Schaltfläche:

    Trigger-E-Mail-Erweiterung installieren

  • Befehlszeile: Führen Sie den folgenden Befehl aus: 

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

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

Erweiterung verwenden

Nach der Installation überwacht diese Erweiterung alle Dokumenteinschreibungen in der von Ihnen konfigurierten Sammlung. Die E-Mail wird basierend auf dem Inhalt der Felder des Dokuments gesendet. In den Feldern der obersten Ebene werden der Absender und die Empfänger der E-Mail angegeben. Das Feld message enthält die Details der zu sendenden E-Mail, einschließlich des E-Mail-Texts.

Beispiel: E-Mail senden

Wenn Sie eine einfache Nachricht senden möchten, fügen Sie Ihrer Sammlung „messages“ ein Dokument mit einem to-Feld und einem message-Feld mit dem folgenden 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.',
}

Felder für Absender und Empfänger

Die Felder der obersten Ebene des Dokuments enthalten Informationen zum E-Mail-Absender und -Empfänger. Verfügbare Felder sind:

  • from: Die E-Mail-Adresse des Absenders. Wenn im Dokument nichts angegeben ist, wird der konfigurierte Parameter „Standard-Absenderadresse“ verwendet.
  • replyTo:Die E-Mail-Adresse, an die Antworten gesendet werden sollen. Wenn im Dokument keine Angabe erfolgt, wird der konfigurierte Parameter „Standard-REPLY-TO-Adresse“ verwendet.
  • to:Eine einzelne E-Mail-Adresse des Empfängers oder ein Array mit mehreren E-Mail-Adressen des Empfängers.
  • toUids:Ein Array, das die Empfänger-UIDs enthält.
  • cc:Eine einzelne E-Mail-Adresse des Empfängers oder ein Array mit mehreren E-Mail-Adressen des Empfängers.
  • ccUids: Ein Array mit den UIDs der Cc-Empfänger.
  • bcc: Eine einzelne E-Mail-Adresse des Empfängers oder ein Array mit mehreren E-Mail-Adressen des Empfängers.
  • bccUids:Ein Array, das die UIDs der Bcc-Empfänger enthält.
  • headers:Ein Objekt mit zusätzlichen Kopfzeilenfeldern (z. B. {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

HINWEIS: Bei den Optionen toUids, ccUids und bccUids werden E-Mails basierend auf Nutzer-UIDs gesendet, die mit E-Mail-Adressen in einem Cloud Firestore-Dokument verknüpft sind. Damit Sie diese Empfängeroptionen verwenden können, müssen Sie eine Cloud Firestore-Sammlung für den Parameter "Nutzersammlung" der Erweiterung angeben. Die Erweiterung kann dann das Feld email für jede UID lesen, die in den Feldern toUids, ccUids und/oder bccUids angegeben ist.

Nachrichtenfeld

Das Feld message des Dokuments enthält Rohdaten zur Zustellung der E-Mail. Dieses Feld sollte in der Regel nur mit vertrauenswürdigem Code ausgefüllt werden, der auf Ihren eigenen Servern oder in Cloud Functions ausgeführt wird. Weitere Informationen finden Sie unten im Abschnitt „Sicherheitsregeln und E-Mail-Versand“.

Verfügbare Properties für das Feld message:

  • messageId: Ein Nachrichten-ID-Header für die E-Mail, falls vorhanden.
  • subject: 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.
  • attachments:Ein Array mit Anhängen. Folgende Nodemailer-Optionen werden unterstützt: UTF-8-String, benutzerdefinierter Inhaltstyp, URL, codierter String, Daten-URI und vorab generierter MIME-Knoten. Beachten Sie, dass Ihre E-Mail keinen Zugriff auf das Dateisystem des Cloud-Servers hat.

Erweiterte Nutzung

Weitere Informationen zur erweiterten Verwendung dieser Erweiterung: