Utiliser l'extension Envoyer un e-mail

L'extension Trigger Email (firestore-send-email) vous permet d'envoyer automatiquement des messages e-mails basés sur les documents d'une collection Cloud Firestore. L'ajout d'un document à la collection déclenche l'envoi d'un e-mail créé à partir des champs du document. Les champs de premier niveau du document indiquent l'expéditeur de l'e-mail et destinataires, y compris les options to, cc et bcc (chacune prenant en charge les UID). La Le champ message du document spécifie les autres éléments de l'adresse e-mail, comme l'objet et le corps de l'e-mail (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 aussi configurer cette extension pour qu'elle affiche les e-mails à l'aide de Modèles Handlebars

Configuration préalable à l'installation

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

  1. Configurez votre service de courrier sortant.

    Lorsque vous installez l'extension d'envoi d'e-mails par déclencheur, vous devez spécifier les informations de connexion et d'authentification d'un serveur SMTP, que l'extension utilise pour envoyer des e-mails. Il s'agit généralement d'un service d'envoi d'e-mails 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 envoyés par e-mail.

    L'extension Trigger Email écoute les nouveaux documents dans un Cloud Firestore. que vous spécifiez. Lorsqu'elle détecte un nouveau document, l'extension envoie un e-mail en fonction des 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 d'e-mails.

    Cette extension permet de déclencher la distribution des e-mails directement depuis le client. applications. Toutefois, vous devez contrôler attentivement 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 assurez-vous toujours que les e-mails sont envoyés uniquement aux destinataires prévus et les contenus de format libre sont réduits au minimum. Les modèles sont là pour vous aider. vous pouvez utiliser des règles de sécurité pour vérifier que les données modèle répond à vos attentes quant à ce qu'un utilisateur doit avoir ou un déclencheur spécifique.

  4. Facultatif: Configurez une collection d'utilisateurs.

    Pour une utilisation de base de cette extension, vous spécifiez les destinataires d'un e-mail en indiquant leurs adresses e-mail dans les champs to, cc et bcc du document de message. Si vous disposez d'une base de données utilisateur Cloud Firestore, vous pouvez spécifier les destinataires à l'aide de la méthode UID Pour que cela fonctionne, votre collection d'utilisateurs doit répondre aux critères suivants :

    • La collection doit être basée sur les ID utilisateur. Autrement dit, l'ID de document de chaque document utilisateur de la collection doit être l'UID Firebase Authentication de l'utilisateur.
    • Chaque document d'utilisateur doit comporter un champ email contenant l'adresse e-mail de l'utilisateur adresse e-mail.

  5. Facultatif : Configurez une collection de modèles.

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

    Pour en savoir plus, consultez Utiliser des modèles Handlebars avec l'extension d'e-mail de déclenchement.

Installer l'extension

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

  • Console Firebase : cliquez sur le bouton suivant.

    Installer l'extension Envoyer un e-mail

  • CLI : exécutez la commande suivante : 

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

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

Utiliser l'extension

Une fois installée, cette extension surveille toutes les écritures de documents dans la collection que vous avez configurée. L'e-mail est distribué 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 à envoyer, 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 à l'aide d'un 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 d'expéditeur et de destinataire

Les champs de premier niveau du document indiquent l'expéditeur et le destinataire de l'e-mail. des informations. Les champs disponibles sont les suivants :

  • from:adresse e-mail de l'expéditeur. Si aucune valeur n'est spécifiée dans le document, utilise l'adresse FROM par défaut configurée .
  • replyTo : adresse e-mail de réponse. Si aucune valeur n'est spécifiée dans le document, utilise l'adresse de réponse par défaut configurée .
  • to : adresse e-mail d'un seul destinataire ou tableau contenant plusieurs adresses e-mail de destinataires.
  • toUids : tableau contenant les UID des destinataires.
  • cc:adresse e-mail d'un destinataire unique ou tableau contenant plusieurs adresses e-mail de destinataires.
  • ccUids:tableau contenant les UID des destinataires en copie.
  • bcc : adresse e-mail d'un seul destinataire ou tableau contenant plusieurs adresses e-mail de destinataires.
  • bccUids : tableau contenant les UID des destinataires de l'objet "Cci".
  • headers : 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 permettent de distribuer des e-mails en fonction de les UID utilisateur associés à des adresses e-mail dans un document Cloud Firestore. Pour utiliser ces options de destinataires, vous devez spécifier une collection Cloud Firestore pour le paramètre "Collection d'utilisateurs" de l'extension. L'extension peut alors lire Champ email pour chaque UID spécifié dans les champs toUids, ccUids et/ou bccUids.

Champ de message

Le champ message du document contient des informations brutes sur la diffusion de l'e-mail. En règle générale, ce champ ne doit être renseigné que par du code approuvé exécuté sur vos propres serveurs ou dans Cloud Functions (voir la section "Règles de sécurité et envoi d'e-mails" ci-dessous).

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

  • messageId:en-tête de l'ID de l'e-mail, le cas échéant.
  • subject : objet de l'e-mail.
  • text : contenu brut de l'e-mail.
  • html : contenu HTML de l'e-mail.
  • amp:contenu AMP4EMAIL de l'e-mail.
  • attachments : tableau contenant une ou plusieurs pièces jointes. Options Nodemailer acceptées : chaîne UTF-8, type de contenu personnalisé, URL, chaîne encodée, URI de données et nœud MIME prégénéré (notez que votre e-mail n'a pas accès au système de fichiers du serveur cloud).

Utilisation avancée

En savoir plus sur l'utilisation avancée de cette extension: