Verwenden 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. Das Hinzufügen eines Dokuments zur Sammlung löst diese Erweiterung aus, um eine E-Mail zu senden, die aus den Feldern des Dokuments erstellt wurde. Die Felder der obersten Ebene des Dokuments geben den Absender und die Empfänger der E-Mail an, einschließlich der Optionen to , cc und bcc (die jeweils UIDs unterstützen). Das message des Dokuments gibt die anderen E-Mail-Elemente wie Betreffzeile und E-Mail-Text (entweder Klartext oder HTML) an.

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 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 Postausgangsdienst ein.

    Wenn Sie die Trigger Email-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-Zustelldienst wie Sendgrid, Mailgun oder Mailchimp Transactional Email bereitgestellt, aber es könnte auch ein Server sein, 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 basierend auf den Feldern des Dokuments eine E-Mail. Sie können für diesen Zweck jede Cloud Firestore-Sammlung verwenden; Die Beispiele auf dieser Seite verwenden eine Sammlung namens email .

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

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

    Die Sicherheitsregeln variieren von Anwendung zu Anwendung, aber Sie sollten immer sicherstellen, dass E-Mails nur an die beabsichtigten Empfänger gesendet werden und freier Inhalt auf ein Minimum beschränkt wird. Vorlagen können hier helfen – Sie können Sicherheitsregeln verwenden, um zu überprüfen, ob die Daten, die in die Vorlage eingefügt werden, Ihren Erwartungen in Bezug darauf entsprechen, was ein Benutzer auslösen darf.

  4. Optional: Richten Sie eine Benutzersammlung 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 ü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 nach Benutzer-IDs verschlüsselt sein. Das heißt, die Dokument-ID jedes Benutzerdokuments in der Sammlung muss die Firebase-Authentifizierungs-UID des Benutzers sein.
    • Jedes Benutzerdokument muss ein E- email -Feld haben, das die E-Mail-Adresse des Benutzers enthält.
  5. Optional: Richten Sie eine Vorlagensammlung 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 Verwenden von Handlebars-Vorlagen mit der Trigger-E-Mail-Erweiterung .

Installieren Sie die Erweiterung

Befolgen Sie zum Installieren der Erweiterung die Schritte auf der Seite Firebase-Erweiterung installieren . Führen Sie zusammenfassend einen der folgenden Schritte aus:

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

Verwenden Sie die Erweiterung

Nach der Installation überwacht diese Erweiterung alle Dokumentschreibvorgänge in die von Ihnen konfigurierte Sammlung. Die E-Mail wird basierend auf dem Inhalt der Dokumentfelder 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: E-Mail senden

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 Absender- und Empfängerinformationen der E-Mail. Verfügbare Felder sind:

  • from: Die E-Mail-Adresse des Absenders. Wenn nicht im Dokument angegeben, wird der konfigurierte Parameter "Default FROM address" verwendet.
  • answerTo: Die Antwort-E-Mail-Adresse. Wenn nicht im Dokument angegeben, wird der konfigurierte Parameter "Default REPLY-TO address" verwendet.
  • to: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • toUids: Ein Array, das die Empfänger-UIDs enthält.
  • cc: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • ccUids: Ein Array, das die CC-Empfänger-UIDs enthält.
  • bcc: Eine einzelne Empfänger-E-Mail-Adresse oder ein Array mit mehreren Empfänger-E-Mail-Adressen.
  • bccUids: Ein Array, das die BCC-Empfänger-UIDs enthält.
  • headers: Ein Objekt zusätzlicher Header-Felder (z. B. {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

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

Nachrichtenfeld

Das message des Dokuments enthält rohe Zustellinformationen für die E-Mail. Dieses Feld sollte im Allgemeinen nur mit 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 Nutzung

Erfahren Sie mehr über die erweiterte Verwendung dieser Erweiterung: