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 diese Erweiterung ausgelöst und eine E‑Mail gesendet, die aus den Feldern des Dokuments erstellt wurde. In den Feldern der obersten Ebene des Dokuments werden der Absender und die Empfänger der E‑Mail 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 angegeben, z. B. die Betreffzeile und der E‑Mail-Text (entweder Nur-Text oder HTML).

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

Bevor Sie die Erweiterung installieren, führen Sie 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. Diese werden in der Regel von einem E‑Mail-Zustellungsdienst wie Sendgrid, Mailgun oder Mailchimp Transactional Email bereitgestellt, können aber auch von einem selbst betriebenen Server stammen.

  2. Erstellen Sie eine Sammlung für E‑Mail-Dokumente.

    Die Erweiterung „E‑Mail auslösen“ überwacht eine von Ihnen angegebene Cloud Firestore Sammlung auf neue Dokumente. Wenn ein neues Dokument gefunden wird, sendet die Erweiterung eine E‑Mail basierend auf den Feldern des Dokuments. 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 für E‑Mail-Dokumente ein.

    Mit dieser Erweiterung kann die E‑Mail-Zustellung direkt von Client anwendungen aus ausgelöst werden. Sie sollten den Clientzugriff auf die Sammlung jedoch sorgfältig kontrollieren, um potenziellen Missbrauch zu vermeiden. Nutzer sollen keine beliebigen E‑Mails von der Adresse Ihres Unternehmens senden können.

    Die Sicherheitsregeln variieren je nach Anwendung. Sie sollten jedoch immer darauf achten, dass E‑Mails nur an die vorgesehenen Empfänger gesendet werden und Freiforminhalte auf ein Minimum beschränkt sind. Vorlagen können hier hilfreich sein. Sie können Sicherheitsregeln verwenden, um zu prüfen, ob die Daten, die in die Vorlage eingefügt werden, Ihren Erwartungen entsprechen und ob ein Nutzer die entsprechenden Aktionen auslösen darf.

  4. Optional: Richten Sie eine Nutzersammlung 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, wenn Sie eine Nutzerdatenbank in Cloud Firestore, Empfänger mithilfe der UIDs der Nutzer angeben. Dazu muss Ihre Nutzersammlung die folgenden Kriterien erfüllen:

    • Die Sammlung muss nach Nutzer-IDs strukturiert sein. Das heißt, die Dokument-ID jedes Nutzerdokuments in der Sammlung muss die Firebase Authentication UID des Nutzers sein.
    • Jedes Nutzerdokument muss ein Feld email mit der E‑Mail-Adresse des Nutzers enthalten.

  5. Optional: Richten Sie eine Sammlung für 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 „E‑Mail auslösen“ verwenden.

Erweiterung installieren

Folgen Sie der Anleitung auf der Seite Firebase Extension, um die Erweiterung zu installieren. Zusammenfassend lässt sich sagen, dass Sie eine der folgenden Aktionen ausführen müssen:

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

Erweiterung verwenden

Nach der Installation überwacht diese Erweiterung alle Dokumentvorgänge in der von Ihnen konfigurierten Sammlung. Die E‑Mail wird basierend auf dem Inhalt der Felder des Dokuments zugestellt. 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 Nachrichtensammlung 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 die Informationen zum Absender und Empfänger der E‑Mail. Verfügbare Felder sind:

  • from: Die E‑Mail-Adresse des Absenders. Wenn sie im Dokument nicht angegeben ist, wird der konfigurierte Parameter „Standardadresse für ‚Von‘“ verwendet.
  • replyTo: Die E‑Mail-Adresse für Antworten. Wenn sie im Dokument nicht angegeben ist, wird der konfigurierte Parameter „Standardadresse für ‚Antworten an‘“ 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 UIDs der Empfänger.
  • 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 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:Mit den Optionen toUids, ccUids und bccUids werden E‑Mails basierend auf Nutzer-UIDs zugestellt, 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 „Nutzersammlung“ der Erweiterung eine Cloud Firestore-Sammlung angeben. Die Erweiterung kann dann das email Feld für jede UID lesen, die in den toUids, ccUids, und/oder bccUids Feldern angegeben ist.

Feld „Nachricht“

Das Feld message des Dokuments enthält Rohdaten zur Zustellung der E‑Mail. Dieses Feld sollte in der Regel nur von vertrauenswürdigem Code gefüllt werden, der auf Ihren eigenen Servern oder in Cloud Functions ausgeführt wird (siehe Abschnitt "Sicherheitsregeln und E‑Mails senden" weiter unten).

Verfügbare Eigenschaften für das message Feld sind:

  • messageId: Ein Header mit der Nachrichten-ID für die E‑Mail, falls vorhanden.
  • subject: Der Betreff der E‑Mail.
  • text: Der Nur-Text-Inhalt 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 Nutzung dieser Erweiterung: