Trigger-E-Mail-Erweiterung verwenden

Mit der Erweiterung „E‑Mail auslösen“ (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, wird durch diese Erweiterung eine E-Mail gesendet, die aus den Feldern des Dokuments erstellt wurde. In den Feldern der obersten Ebene des Dokuments werden der E-Mail-Absender und die Empfänger angegeben, einschließlich der Optionen to, cc und bcc (die jeweils UIDs unterstützen). Im Feld message des Dokuments werden die anderen E-Mail-Elemente wie Betreffzeile und E-Mail-Text (entweder Nur-Text oder HTML) angegeben.

Hier ist ein einfaches Beispiel für einen Dokumentvorgang, der 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.',
  },
})

Optional können Sie diese Erweiterung auch so konfigurieren, dass E-Mails mit Handlebars-Vorlagen gerendert werden.

Einrichtung vor der Installation

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

  1. Richten Sie Ihren Dienst für ausgehende E‑Mails ein.

    Wenn Sie die Erweiterung „E-Mail auslösen“ installieren, müssen Sie die Verbindungs- und Authentifizierungsdetails eines SMTP-Servers angeben, über den die Erweiterung E-Mails sendet. Dieser wird in der Regel von einem E-Mail-Zustelldienst wie Sendgrid, Mailgun oder Mailchimp Transactional Email bereitgestellt, kann aber auch ein von Ihnen selbst betriebener Server sein.

  2. Sammlung von E‑Mail-Dokumenten erstellen

    Die Erweiterung „E‑Mail auslösen“ überwacht neue Dokumente in einer von Ihnen angegebenen Cloud FirestoreSammlung. Wenn die Erweiterung ein neues Dokument findet, wird eine E-Mail basierend auf den Feldern des Dokuments gesendet. Sie können dafür eine beliebige Cloud Firestore-Sammlung verwenden. In den Beispielen auf dieser Seite wird eine Sammlung mit dem Namen email verwendet.

  3. Richten Sie Sicherheitsregeln für Ihre Sammlung von E‑Mail-Dokumenten ein.

    Mit dieser Erweiterung kann die E‑Mail-Zustellung direkt über Clientanwendungen ausgelöst werden. Sie sollten den Clientzugriff auf die Sammlung jedoch sorgfältig steuern, um potenziellen Missbrauch zu vermeiden. Nutzer sollten nicht in der Lage sein, beliebige E-Mails von der Adresse Ihres Unternehmens zu senden.

    Sicherheitsregeln variieren von Anwendung zu Anwendung. Sie sollten jedoch immer darauf achten, dass E-Mails nur an die vorgesehenen Empfänger gesendet werden und dass Freiforminhalte auf ein Minimum beschränkt werden. Vorlagen können hier helfen. Mit 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 für 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. Alternativ können Sie Empfänger angeben, indem Sie die UIDs der Nutzer verwenden, wenn Sie eine Nutzerdatenbank in Cloud Firestore haben. Damit das funktioniert, muss Ihre Sammlung von Nutzern die folgenden Kriterien erfüllen:

    • Die Erhebung 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 ein Feld email mit der E-Mail-Adresse des Nutzers enthalten.

  5. Optional: Richten Sie eine Sammlung von Vorlagen ein.

    Sie können 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 Erweiterung „Trigger Email“ verwenden.

Erweiterung installieren

Folgen Sie der Anleitung auf der Seite Firebase Extension installieren, um die Erweiterung zu installieren. Führen Sie einen der folgenden Schritte aus:

  • Firebase-Konsole:Klicken Sie auf die folgende Schaltfläche:

    Erweiterung „Trigger Email“ 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 Schreibvorgänge für Dokumente in der von Ihnen konfigurierten Sammlung. E-Mails werden basierend auf dem Inhalt der Felder des Dokuments gesendet. In den Feldern auf oberster 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 Feld to und einem Feld 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.',
}

Felder für Absender und Empfänger

Die Felder der obersten Ebene des Dokuments enthalten die Informationen zum Absender und Empfänger der E‑Mail. Folgende Felder sind verfügbar:

  • from: Die E-Mail-Adresse des Absenders. Wenn nicht im Dokument angegeben, wird der konfigurierte Parameter „Standard-Absenderadresse“ verwendet.
  • replyTo:Die Antwort-E-Mail-Adresse. Wenn nicht im Dokument angegeben, wird der konfigurierte Parameter „Standard-ANTWORT-AN-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 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 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 mit den UIDs der BCC-Empfänger.
  • headers:Ein Objekt mit zusätzlichen Headerfeldern (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 in einem Cloud Firestore-Dokument mit E-Mail-Adressen verknüpft sind. Wenn Sie diese Empfängeroptionen verwenden möchten, müssen Sie für den Parameter „Users collection“ (Nutzersammlung) der Erweiterung eine Cloud Firestore-Sammlung 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 von vertrauenswürdigem Code ausgefüllt werden, der auf Ihren eigenen Servern oder in Cloud Functions ausgeführt wird (siehe Abschnitt „Sicherheitsregeln und E-Mail-Versand“ unten).

Folgende Eigenschaften sind für das Feld message verfügbar:

  • 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. Unterstützte Nodemailer-Optionen: UTF-8-String, benutzerdefinierter Inhaltstyp, URL, codierter String, Daten-URI und vorgefertigter 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: