Utiliser l'extension Envoyer un e-mail

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

Voici un exemple de base d'écriture de document 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 configurer cette extension pour afficher 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 messagerie sortante.

    Lorsque vous installez l'extension Trigger Email, vous devez spécifier les informations de connexion et d'authentification d'un serveur SMTP, que l'extension utilise pour envoyer des e-mails. Ces informations sont généralement fournies par un service de distribution d'e-mails tel que Sendgrid, Mailgun ou Mailchimp Transactional Email, mais il peut également s'agir d'un serveur que vous exécutez vous-même.

  2. Créez une collection de documents d'e-mails.

    L'extension Trigger Email écoute les nouveaux documents dans une Cloud Firestore collection que vous spécifiez. Lorsqu'elle trouve un nouveau document, l'extension envoie un e-mail en fonction des champs du document. Vous pouvez utiliser n'importe quelle Cloud Firestore collection à cet effet. 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 peut être utilisée pour déclencher la distribution d'e-mails directement à partir d'applications clientes. Toutefois, 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 ne sont envoyés qu'aux destinataires prévus et que le contenu libre est réduit au minimum. Les modèles peuvent vous aider. Vous pouvez utiliser des règles de sécurité pour vérifier que les données renseignées dans le modèle correspondent à ce qu'un utilisateur doit ê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 indiquant leur adresse e-mail dans les champs to, cc, et bcc du document de message. Vous pouvez également spécifier les destinataires à l'aide de leur UID si vous disposez d'une base de données utilisateur dans Cloud Firestore. Pour que cela fonctionne, votre collection d'utilisateurs doit répondre aux critères suivants :

    • La collection doit être indexé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 utilisateur doit comporter un champ email contenant l'adresse e-mail de l'utilisateur.

  5. (Facultatif) Configurez une collection de modèles.

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

    Pour en savoir plus, consultez Utiliser des modèles Handlebars avec l'extension Trigger Email.

Installer l'extension

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

  • Firebase console : cliquez sur le bouton suivant :

    Installer 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 êtes 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 distribué en fonction du contenu des champs du document. Les champs de premier niveau spécifient l'expéditeur et les destinataires de l'e-mail. Le champ message contient les détails de l'e-mail à distribuer, 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 contenant les éléments suivants :

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 premier niveau du document fournissent les informations sur l'expéditeur et le destinataire de l'e-mail. Parmi les suivants :

  • from : adresse e-mail de l'expéditeur. Si elle n'est pas spécifiée dans le document, utilise le paramètre configuré "Adresse FROM par défaut".
  • replyTo : adresse e-mail de réponse. Si elle n'est pas spécifiée dans le document, utilise le paramètre configuré "Adresse de réponse par défaut".
  • 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 seul destinataire 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 en copie cachée.
  • 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 distribuent les 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 d'utilisateurs" de l'extension. L'extension peut ensuite lire le email champ pour chaque UID spécifié dans les toUids, ccUids, et/ou bccUids champs.

Champ de message

Le champ message du document contient des informations de distribution brutes pour l'e-mail. Ce champ ne doit généralement être renseigné que par du code approuvé s'exécutant sur vos propres serveurs ou dans 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 les suivantes :

  • messageId : en-tête d'ID de message pour l'e-mail, le cas échéant.
  • subject : objet de l'e-mail.
  • text : contenu en texte 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 compatibles : 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é (sachez que votre e-mail n'a pas accès au système de fichiers du serveur cloud).

Pour une utilisation avancée

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