Comment envoyer un e-mail avec PHP à l'aide de Twilio SendGrid et Mezzio

Publié: 2021-03-24

Le courrier électronique est un outil de communication aussi important que jamais. Pour vous aider à mieux tirer parti des e-mails, je vais vous montrer comment envoyer des e-mails à l'aide du framework Mezzio de PHP et de l'API de Twilio SendGrid.

Plus précisément, vous allez apprendre à envoyer des e-mails avec des corps en texte brut et HTML, et cela inclut une pièce jointe PDF. Vous apprendrez également à utiliser la fonctionnalité de modèles transactionnels de Twilio SendGrid pour simplifier la création de corps d'e-mail, tant par l'équipe de développement que par toute autre équipe de votre organisation.

Ça a l'air bien? Commençons.

Présentation rapide de l'application

Pour rendre ce didacticiel plus significatif, imaginez que le code que nous allons écrire fait partie d'une boutique de commerce électronique en ligne fictive construite avec Mezzio, nommée The Little PHP Shop - en particulier, la partie immédiatement après qu'un client ait effectué un achat. À ce stade du flux d'utilisateurs, le client reçoit un e-mail le remerciant pour son achat et inclut une facture PDF pour ses archives.

Nous allons créer une classe Handler pour envoyer l'e-mail post-achat, qui recevra les détails d'achat d'une commande effectuée par le client. Avec ces informations d'achat, la classe Handler utilisera ensuite plusieurs classes de l'API PHP SendGrid pour créer et envoyer l'e-mail de confirmation d'achat.

Parmi ceux-ci, les plus importants sont "SendGrid\Mail\Mail" et "\SendGrid". "SendGrid\Mail\Mail" est l'objet qui stocke toutes les propriétés d'un message électronique que nous enverrons via Twilio SendGrid. L'objet "SendGrid" forme la couche de transport, facilitant l'envoi d'e-mails via Twilio SendGrid.

Conditions préalables

Pour terminer ce didacticiel, vous aurez besoin des 4 éléments suivants dans votre environnement de développement local :

  1. Compte Twilio SendGrid
  2. PHP 7.4 avec les extensions SSL cURL , mbstring et Open installées et activées
  3. Composer installé globalement
  4. boucle

Échafauder l'application Mezzio

Nous devons d'abord créer l'application de base. Pour ce faire, nous allons, comme toujours, utiliser le Mezzio Skeleton pour le faire à notre place. Une fois que nous avons échafaudé l'application de base, nous passerons au répertoire de projet nouvellement créé. Exécutez ensuite les commandes suivantes dans votre terminal, en suivant les invites de la première :

Installer les dépendances requises

Avec le projet échafaudé, nous devons ajouter 3 dépendances supplémentaires pour terminer le projet. Ceux-ci sont:

  • Bibliothèque d' API PHP de Twilio SendGrid pour interagir avec l'API Twilio SendGrid
  • Client HTTP PHP pour l'envoi de requêtes HTTP
  • PHP Dotenv pour stocker et récupérer des variables d'environnement

Pour les installer, exécutez la commande suivante dans votre terminal :

Initialiser PHP Dotenv

Une fois les dépendances installées, nous chargeons PHP Dotenv afin qu'il lise les variables définies dans ".env" et les rende disponibles pour PHP en tant que variables d'environnement. Pour ce faire, insérez le code suivant dans « public/index.php », juste après « require vendor/autoload.php ».

Ajoutez les détails de votre compte Twilio SendGrid

Vous devez maintenant fournir à l'application votre clé API SendGrid. Pour ce faire, après vous être connecté à Twilio SendGrid , accédez à "Paramètres -> Clés API ". " Une fois là:

  1. Cliquez sur " Créer une clé API " pour créer une clé API
  2. Donnez un nom à la nouvelle clé API, acceptez l'autorisation de clé API par défaut de " Accès complet " , et cliquez sur " Créer et afficher "

Une fois la clé API créée, cliquez et copiez la clé, puis cliquez sur " Terminé " . ”

Après cela, ajoutez 2 clés supplémentaires au fichier : "SENDGRID_DEFAULT_SENDER_ADDRESS" et "SENDGRID_DEFAULT_SENDER_NAME". Comme les noms l'indiquent, il s'agit de l'adresse e-mail et du nom que nous utiliserons pour tous les e-mails envoyés depuis notre application, à moins qu'ils ne soient remplacés.

Remarque : Pour ce faire, dans Authentification de l'expéditeur , assurez-vous qu'il indique "Vérifié" dans le tableau "Vérification de l'expéditeur unique".

Définir les détails de configuration de la messagerie de l'application

En plus de la clé API Twilio SendGrid, nous allons stocker quelques autres paramètres de configuration de messagerie globale. Plus précisément, nous allons définir une adresse e-mail d'expédition et de réponse et un nom que nous utiliserons dans chaque e-mail. De cette façon, nous n'avons pas à les définir à chaque fois.

Nous allons également créer 2 modèles de corps d'e-mail : un pour les e-mails en texte brut et un pour les e-mails HTML. Pour ce faire, dans « config/autoload », créez un nouveau fichier nommé « mail.global.php » et ajoutez-y le code suivant.

Créer une classe pour instancier un objet mail

Une fois les détails de configuration de l'application clé définis, créons maintenant une classe qui instanciera un objet de messagerie de base avec les propriétés par défaut définies. Pour ce faire, dans un nouveau répertoire, "src/App/src/Mailer", créez un nouveau fichier appelé "SendGridMailMessageFactory.php", et ajoutez-y le code ci-dessous.

Lorsque nous invoquons la classe, elle a accès au conteneur d'injection de dépendance (DI) de l'application, à partir duquel elle récupère les détails de configuration que nous avons stockés dans "config/autoload/mail.global.php".

Après cela, il instanciera un nouvel objet "SendGrid\Mail\Mail" et définira les détails de et de réponse en transmettant les détails de configuration respectifs aux appels aux méthodes "Mail", "setFrom" et "setReplyTo", respectivement. Après cela, il renverra l'objet "Mail" instancié.

Pour l'utiliser, cependant, vous devez l'enregistrer avec le conteneur DI. Pour ce faire, dans "src/App/src/ConfigProvider", ajoutez l'entrée suivante à l'élément "factories" dans le tableau renvoyé par la méthode "getDependencies".

Créer un gestionnaire pour envoyer des e-mails

Nous devons ensuite créer une classe Handler pour composer et envoyer des e-mails. Pour ce faire, nous utiliserons les outils CLI de Mezzio , disponibles via Composer, en exécutant la commande ci-dessous.

L'exécution de la commande ci-dessus fait quatre choses pour nous :

  1. Crée une nouvelle classe Handler, "src/App/Handler/EmailSenderHandler.php "
  2. Crée une classe de fabrique pour instancier la classe Handler, "src/App/Handler/EmailSenderHandlerFactory.php"
  3. Crée un fichier modèle ("src/App/templates/app/email-sender.html.<ext>"), dont nous n'aurons pas besoin . Le nom de fichier "<ext>" est déterminé par le moteur de template que vous avez choisi lors de l'étape "create-project".
  4. Enregistre la nouvelle classe Handler en tant que service dans le conteneur DI en ajoutant une entrée à "config/autoload/mezzio-tooling-factories.global.php"

Refactoriser le gestionnaire pour envoyer des e-mails

Avec "EmailSenderHandler.php" créé, nous devons maintenant le refactoriser pour qu'il puisse envoyer des e-mails. Pour ce faire, nous allons d'abord refactoriser le constructeur "EmailSenderHandler", en remplaçant le paramètre "TemplateRendererInterface" par 3 nouveaux paramètres. Celles-ci initialiseront 3 nouvelles variables de membre de classe :

  • Un objet "\SendGrid\Mail\Mail"
  • Un objet "\SendGrid"
  • Un tableau contenant les détails de configuration requis

Vous pouvez voir le constructeur révisé dans l'exemple ci-dessous, ainsi que les variables de membre de classe associées. Remplacez la variable de membre de classe existante et le constructeur par ce code.

Remarque : Ensuite, nous devons refactoriser la méthode "handle". Remplacez le contenu existant de la méthode "handle" "EmailSenderHandler" par le code ci-dessous, puis passons en revue ce qu'il fait.

Il commence par utiliser "$request->getParsedBody()" pour récupérer tous les paramètres fournis dans le corps de la requête, qui renverra un tableau associatif, initialisant "$details". Avec les paramètres disponibles, il appelle la méthode "addTo" de l'objet "SendGrid\Mail\Mail" pour définir le destinataire de l'e-mail, en transmettant l'adresse e-mail et le nom du destinataire dans les 2 premiers arguments et un tableau de substitutions dans le troisième argument.

Les substitutions vous permettent de personnaliser les messages électroniques pour chaque destinataire. Dans les e-mails en texte brut, toute chaîne immédiatement entourée de tirets, par exemple, "-first_name-" est une substitution. Dans les e-mails HTML, il utilise la syntaxe Handlebars , qui entoure les chaînes de doubles parenthèses, par exemple, "{{ first_name }}".

Ensuite, nous définissons le sujet du message et ajoutons un corps de message en texte brut et HTML. Avec cela, notre e-mail est prêt à être envoyé. Nous utilisons donc l'objet "SendGrid", "$this->mailer", pour l'envoyer, en initialisant une nouvelle variable, "$response", avec la réponse de la tentative d'envoi du message. Enfin, nous renvoyons un objet JsonResponse , contenant le code d'état et le corps de la réponse.

Remarque : Refactoriser la méthode __invoke d'EmailSenderHandlerFactory

Maintenant que nous avons terminé la refactorisation de « EmailSenderHandler », nous devons refactoriser « EmailSenderHandlerFactory ». Cela instancie "EmailSenderHandler" correctement. Pour ce faire, remplacez la définition existante de sa méthode "__invoke`" par le code suivant.

Cela récupère un objet "\SendGrid\Mail\Mail" du conteneur DI, préinitialisé avec l'expéditeur et répond aux détails de l'e-mail, et initialise un nouvel objet nommé "$message". Il instancie ensuite un nouvel objet "SendGrid", nommé "$mailer" pour envoyer le message électronique. Enfin, il récupère la configuration de la messagerie à partir de la configuration de l'application. Ensuite, il les utilise pour initialiser et renvoyer l'objet "EmailSenderHandler".

Mettre à jour la table de routage

Avec tous ces changements, il reste un dernier changement à faire avant de pouvoir tester le code et envoyer un e-mail. Nous devons mettre à jour la table de routage afin que la route par défaut utilise notre nouvelle classe Handler comme gestionnaire de route, au lieu de "HomePageHandler". Pour ce faire, remplacez la définition de la route par défaut dans « config/routes.php » par l'exemple suivant.

Envoyer le premier e-mail

Il est maintenant temps d'envoyer le premier e-mail. Pour ce faire, démarrez d'abord l'application en exécutant la commande ci-dessous dans le terminal.

Ensuite, à l'aide de cURL, envoyez une requête GET à " http://localhost:8080 ", comme dans l'exemple ci-dessous, en remplaçant les valeurs entre crochets par les détails pertinents pour votre e-mail.

Vous devriez voir la sortie "{"status":202,"message":""}" sur le terminal, et vous devriez recevoir un e-mail qui ressemble à l'image ci-dessous.

Remarque : Utiliser des modèles d'e-mails transactionnels au lieu de chaînes de modèles

Bien que nous ayons pu envoyer un e-mail avec à la fois un texte brut et un corps HTML, la façon dont nous l'avons fait n'est cependant pas idéale. Pour chaque e-mail que nous envoyons (et notre application peut finir par en envoyer plusieurs), nous devrons leur ajouter un texte en clair et un corps HTML.

Mais le stockage des définitions du corps de l'e-mail dans le code place la majeure partie de l'effort sur l'équipe de développement. Cependant, du moins d'après mon expérience, il arrive souvent que d'autres équipes, souvent du marketing, créent et maintiennent des modèles d'e-mails.

Donc, pour cette raison, et parce que cela accélérerait le développement et répartirait la charge entre plusieurs équipes, nous allons refactoriser l'application pour utiliser des modèles d'e-mails transactionnels . Vous pouvez les créer et les gérer via l'interface utilisateur Twilio SendGrid par les membres de l'équipe qui peuvent avoir peu ou pas d'expérience technique, plutôt que dans le code.

Si vous n'en avez pas entendu parler, le glossaire Twilio SendGrid les définit comme suit :

Les modèles d'e-mails transactionnels sont des mises en page d'e-mails précodées que les spécialistes du marketing, les concepteurs et les développeurs peuvent utiliser pour créer rapidement et facilement des campagnes d'e-mails transactionnels. Les modèles d'e-mails transactionnels de Twilio SendGrid permettent aux personnes non techniques et techniques d'apporter des modifications en temps réel à l'e-mail que leurs destinataires reçoivent.

Pour cet article, nous n'avons besoin que d'un article assez basique. Pour ce faire, suivez les détails de la documentation de Twilio SendGrid et créez-en un dont le contenu est uniquement dans un module à texte unique. Ensuite, pour le corps du texte, utilisez le texte ci-dessous.

Notez qu'il y a 6 substitutions dans l'e-mail :

  • « first_name » : le prénom du client
  • "last_name": le nom de famille du client
  • « sender_name » : Nom de la boutique e-commerce (The Little PHP Shop)
  • « sender_state » : L'état de la boutique e-commerce
  • « sender_country » : Pays de la boutique e-commerce
  • "support_email": L'e-mail d'assistance que les clients peuvent utiliser pour obtenir une assistance après-vente

Compte tenu de cela, nous devons mettre ces informations à la disposition de notre application. Les noms et prénoms du client que nous avons déjà. Les 4 substitutions restantes seront globales, donc comme nous l'avons fait précédemment, nous ajouterons la configuration ci-dessous à « config/autoload/mail.global.php », après l'élément « templates ».

Une fois le nouveau fichier de configuration créé, dans la méthode "handle" "EmailSenderHandler", remplacez les 2 appels à "$this->mail->addContent()" par le code suivant.

Les 2 appels de méthode ajoutent les détails de l'expéditeur et prennent en charge l'adresse e-mail en tant que substitutions globales. Ces substitutions s'appliquent au corps de l'e-mail avant toute autre substitution, mais sont annulées s'il existe des substitutions avec la même clé pour un destinataire d'e-mail.

Ensuite, vous devez récupérer l'ID du modèle d'e-mail transactionnel. Vous pouvez le trouver en cliquant sur le nom du modèle dans la liste des modèles , comme vous pouvez le voir dans la capture d'écran ci-dessous.

Copiez-le et stockez-le dans "config/autoload/mail.global.php" dans un nouvel élément avec la clé "template_id" puis supprimez "plain" et "HTML". Une fois terminé, l'élément "mail/templates" du tableau renvoyé ressemblera au code ci-dessous, où "<the template's id>" remplace l'ID de votre template.

Avec la configuration mise à jour, nous devons maintenant ajouter un appel à la méthode "Mail" "setTemplateId" dans la méthode "EmailSenderHandler" "handle", en passant l'ID du modèle que nous venons d'ajouter à "config/autoload/mail.global. php." Vous pouvez voir un exemple dans le code ci-dessous.

Testons les changements

Comme précédemment, en utilisant cURL, faites une requête GET à « http://localhost:8080 » pour tester si les modifications fonctionnent comme prévu. Vous devriez voir la sortie "{"status":202,"message":""}" sur le terminal, comme dans l'exemple précédent. Dans votre boîte de réception, vous devriez voir un bel e-mail, avec les substitutions remplacées, comme dans la capture d'écran ci-dessous.

Joindre une facture PDF

Maintenant que nous utilisons des modèles dynamiques, attachons la facture PDF dont nous avons parlé en haut de l'article. Pour vous faire gagner du temps et des efforts pour en rechercher ou en créer une vous-même, j'ai créé un exemple de facture PDF que vous pouvez utiliser pour cet article. Enregistrez-le dans le répertoire « data » de l'application .

Remarque : Pour joindre une facture, nous devons utiliser la méthode "Mail" "addAttachment", que vous pouvez voir dans l'exemple de code suivant. La méthode prend 5 arguments, mais nous ne fournissons que les 4 premiers. Ce sont :

  1. Un objet « Pièce jointe » ou une chaîne encodée en Base64 . Si la valeur de ce paramètre n'est pas encodée en base64, la méthode le fera pour nous.
  2. Le type mime de la pièce jointe (désormais appelé type de média ).
  3. Le nom de fichier de la pièce jointe . Il s'agit du nom sous lequel le fichier sera enregistré, par défaut, à moins que l'utilisateur ne le modifie.
  4. Disposition du contenu de la pièce jointe . Si vous n'êtes pas familier avec la disposition du contenu, la disposition du contenu en ligne signifie que la pièce jointe doit s'afficher automatiquement lorsque le message s'affiche, et la disposition du contenu de la pièce jointe signifie que la pièce jointe ne s'affiche pas automatiquement et nécessite une certaine forme d'action de la part de l'utilisateur pour ouvrez-le.

Dans l'exemple de code ci-dessous, la méthode file_get_contents de PHP lit le contenu du fichier dans une nouvelle variable nommée "$invoice". Ensuite, le PDF est joint au message en appelant la méthode "addAttachment".

Ici, nous :

  • Transmettez le contenu de la facture, qui sera encodé en Base64
  • Définissez le type MIME sur "application/pdf" car nous attachons un fichier PDF
  • Définissez le nom de fichier de la facture sur un nom fictif auquel un client pourrait raisonnablement s'attendre
  • Définissez la disposition du contenu sur "pièce jointe"

Maintenant que nous avons terminé ces changements, testons qu'ils fonctionnent. Exécutez la même requête cURL que nous avons exécutée les 2 fois précédentes. Ensuite, dans votre boîte de réception, vous devriez voir un bel e-mail avec l'exemple de facture PDF visible lors de la visualisation de l'e-mail.

Voilà comment envoyer des e-mails avec PHP en utilisant Twilio SendGrid et Mezzio

Alors que nous n'avons fait qu'effleurer la surface de ce qui est possible lors de l'envoi d'e-mails avec Twilio SendGrid et Mezzio, vous pouvez désormais envoyer un e-mail avec un corps en texte brut et HTML, ainsi qu'avec une pièce jointe. Vous avez également appris à utiliser des modèles transactionnels et des substitutions que vous pouvez définir globalement et par destinataire.

Je vous encourage fortement à consulter la documentation de la bibliothèque PHP pour voir ce qui est disponible, comme la planification des envois d'e-mails, la pièce jointe d'un fichier d'Amazon S3, l'ajout d'en-têtes et l'ajout de sections et de catégories.

Matthew Setter est éditeur PHP au sein de l'équipe Twilio Voices et, naturellement, développeur PHP. Il est également l'auteur de Mezzio Essentials . Lorsqu'il n'écrit pas de code PHP, il édite d'excellents articles PHP ici chez Twilio. Il est joignable via :

  • Courriel : [email protected]
  • Web : http://matthewsetter.com
  • Twitter: @settermjd
  • GitHub : https://github.com/settermjd