Utilisation de l'extension Trigger Email

L'extension Trigger Email ( firestore-send-email ) vous permet d'envoyer automatiquement des e-mails en fonction des documents d'une collection Cloud Firestore. L'ajout d'un document à la collection déclenche l'envoi par cette extension d'un e-mail construit à partir des champs du document. Les champs de niveau supérieur du document spécifient l'expéditeur et les destinataires de l'e-mail, y compris les options to , cc et bcc (chacune prenant en charge les UID). Le champ message du document spécifie les autres éléments de l'e-mail, comme la ligne d'objet et le corps de l'e-mail (en texte brut ou HTML).

Voici un exemple d'écriture de document de base qui déclencherait cette extension :

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

Vous pouvez également éventuellement configurer cette extension pour afficher les e-mails à l'aide des modèles de guidon .

Configuration de pré-installation

Avant d'installer l'extension, procédez comme suit :

  1. Configurez votre service de courrier sortant.

    Lorsque vous installez l'extension Trigger Email, vous devrez spécifier les détails de connexion et d'authentification d'un serveur SMTP, que l'extension utilise pour envoyer des e-mails. Ceci est généralement fourni par un service de livraison de courrier électronique tel que Sendgrid, Mailgun ou Mailchimp Transactional Email, mais il peut également s'agir d'un serveur que vous gérez vous-même.

  2. Créez une collection de documents par courrier électronique.

    L'extension Trigger Email écoute les nouveaux documents dans une collection Cloud Firestore que vous spécifiez. Lorsqu'elle trouve un nouveau document, l'extension envoie un e-mail basé sur les champs du document. Vous pouvez utiliser n'importe quelle collection Cloud Firestore à cette fin ; les exemples de cette page utilisent une collection nommée email .

  3. Configurez des règles de sécurité pour votre collection de documents électroniques.

    Cette extension peut être utilisée pour déclencher la livraison d'e-mails directement à partir des applications clientes. Cependant, vous devez contrôler soigneusement l'accès des clients à la collection pour éviter tout abus potentiel (vous ne voulez pas que les utilisateurs puissent envoyer des e-mails arbitraires à partir de l'adresse de votre entreprise !).

    Les règles de sécurité varient d'une application à l'autre, mais vous devez toujours vous assurer que les e-mails sont envoyés uniquement aux destinataires prévus et que le contenu de forme libre est réduit au minimum. Les modèles peuvent être utiles ici : vous pouvez utiliser des règles de sécurité pour vérifier que les données renseignées dans le modèle correspondent à vos attentes quant à ce qu'un utilisateur devrait être autorisé à déclencher.

  4. Facultatif : configurez une collection d'utilisateurs.

    Dans le cadre d'une utilisation de base de cette extension, vous spécifiez les destinataires d'un e-mail en spécifiant leurs adresses e-mail dans les champs to , cc et bcc du document de message. Alternativement, si vous disposez d'une base de données d'utilisateurs dans Cloud Firestore, vous pouvez spécifier les destinataires à l'aide des UID des utilisateurs. Pour que cela fonctionne, votre collection d'utilisateurs doit répondre à ces critères :

    • La collection doit être saisie sur les identifiants des utilisateurs. Autrement dit, l'ID de chaque document utilisateur de la collection doit être l'UID d'authentification Firebase de l'utilisateur.
    • Chaque document utilisateur doit avoir un champ email contenant l'adresse email de l'utilisateur.
  5. Facultatif : configurez une collection de modèles.

    Vous pouvez afficher des e-mails à l'aide des modèles de guidons . Pour ce faire, vous aurez besoin d'une collection Cloud Firestore pour contenir vos modèles.

    Voir Utiliser les modèles guidons avec l'extension Trigger Email pour plus de détails.

Installer l'extension

Pour installer l'extension, suivez les étapes de la page Installer une extension Firebase . En résumé, effectuez l'une des opérations suivantes :

  • Console Firebase : cliquez sur le bouton suivant :

    Installez l'extension Trigger Email

  • CLI : exécutez la commande suivante :

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

Lorsque vous installez l'extension, vous serez invité à spécifier vos informations de connexion SMTP et les collections Cloud Firestore que vous avez configurées précédemment.

Utiliser l'extension

Après l'installation, cette extension surveille toutes les écritures de documents dans la collection que vous avez configurée. L'e-mail est envoyé en fonction du contenu des champs du document. Les champs de niveau supérieur spécifient l'expéditeur et les destinataires de l'e-mail. Le champ message contient les détails de l'e-mail à transmettre, y compris le corps de l'e-mail.

Exemple : envoyer un e-mail

Pour envoyer un message simple, ajoutez un document à votre collection de messages avec un champ to et un champ message avec le contenu suivant :

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

Champs de l'expéditeur et du destinataire

Les champs de niveau supérieur du document fournissent les informations sur l'expéditeur et le destinataire de l'e-mail. Les champs disponibles sont :

  • from : L'adresse e-mail de l'expéditeur. S'il n'est pas spécifié dans le document, utilise le paramètre configuré « Adresse FROM par défaut ».
  • ReplyTo : L'adresse e-mail de réponse. S'il n'est pas spécifié dans le document, utilise le paramètre configuré "Adresse REPLY-TO par défaut".
  • à : une adresse e-mail de destinataire unique ou un tableau contenant plusieurs adresses e-mail de destinataires.
  • toUids : un tableau contenant les UID du destinataire.
  • cc : une adresse e-mail de destinataire unique ou un tableau contenant plusieurs adresses e-mail de destinataires.
  • ccUids : un tableau contenant les UID du destinataire CC.
  • bcc : une adresse e-mail de destinataire unique ou un tableau contenant plusieurs adresses e-mail de destinataires.
  • bccUids : un tableau contenant les UID des destinataires BCC.
  • headers : un objet de champs d'en-tête supplémentaires (par exemple, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

REMARQUE : Les options toUids , ccUids et bccUids envoient des e-mails en fonction des UID utilisateur associés aux adresses e-mail dans un document Cloud Firestore. Pour utiliser ces options de destinataire, vous devez spécifier une collection Cloud Firestore pour le paramètre « Collection Utilisateurs » de l'extension. L'extension peut ensuite lire le champ email pour chaque UID spécifié dans les champs toUids , ccUids et/ou bccUids .

Champ de message

Le champ message du document contient les informations brutes de livraison de l'e-mail. Ce champ ne doit généralement être renseigné que par du code de confiance exécuté sur vos propres serveurs ou Cloud Functions (reportez-vous à la section « Règles de sécurité et envoi d'e-mails » ci-dessous).

Les propriétés disponibles pour le champ message sont :

  • messageId : un en-tête d'ID de message pour l'e-mail, le cas échéant.
  • sujet : le sujet de l'e-mail.
  • text : le contenu en texte brut de l'e-mail.
  • html : Le contenu HTML de l'e-mail.
  • amp : Le contenu AMP4EMAIL de l'e-mail.
  • attachments : un tableau contenant des pièces jointes ; Options Nodemailer prises en charge : chaîne utf-8, type de contenu personnalisé, URL, chaîne codée, URI de données et nœud MIME prégénéré (sachez que votre courrier électronique n'a pas accès au système de fichiers du serveur cloud).

Utilisation avancée

Découvrez une utilisation plus avancée de cette extension :