Envoi d’un email à l’aide de l’API PHP de Mailgun

Ceci est un article invité de Mihály Sáróy, développeur chez EDMdesigner.

Le SDK PHP de Mailgun existe depuis un certain temps déjà, et nous avons constaté de nombreux changements : de nouvelles fonctionnalités, de nouvelles intégrations développées par-dessus, de nouveaux points de terminaison d’API… pourtant, le cœur de PHP reste le même. Puisqu’il s’agissait du premier SDK pour l’API de Mailgun, il a eu le temps d’évoluer et de passer par des itérations qui le rendent facile à utiliser – ce dont nous nous sommes rendu compte en l’essayant.

Dans cet article, nous allons montrer comment vous pouvez implémenter l’API de Mailgun en utilisant PHP avec PEAR.

Nous allons commencer ce tutoriel en rappelant que l’email transactionnel est partout, et qu’il est important de bien faire les choses. Un email qui ne fonctionne pas correctement peut entraîner une perte de revenus pour votre entreprise et créer globalement une mauvaise expérience pour la clientèle.

En tant que développeur, vous cherchez toujours à trouver la solution la plus simple (rapide) et la plus puissante à un problème. Vous y parvenez souvent en remplissant deux conditions :

1. L’utilisation de bibliothèques externes adaptées à votre solution.
2. La conception d’applications évolutives.

Inutile d’expliquer la première condition – vous ne commenceriez pas par créer un système d’exploitation avant de passer au codage d’une application, n’est-ce pas ? Tout au long de cet article, nous verrons comment utiliser des packages préexistants pour envoyer un email. Mais passons maintenant à mon deuxième point : lisez la suite. 

Pour une conception évolutive, c’est là que vous vous tournez vers des services comme Mailgun. Vous pouvez vous attendre à une solution riche en fonctionnalités qui répond aux exigences de l’envoi d’email à fort volume.

Si vous vous souciez de la livraison (et vous le devriez), Mailgun offre une grande fiabilité, car l’outil est conçu pour gérer très efficacement l’email transactionnel. Vous pouvez configurer plusieurs domaines et choisir si vous souhaitez utiliser une IP partagée ou bâtir votre propre réputation. Pour protéger vos en-têtes d’email, Mailgun exige DKIM et le protocole SPF soient ajoutés au compte, et qu’ils passent leurs vérifications au niveau de l’authentification et de l’alignement. Tous ces éléments fonctionnent ensemble pour vous aider dans la livraison d’email.

Passons maintenant aux choses sérieuses : la configuration d’un script wrapper PHP pour Mailgun. Dans un premier temps, nous utiliserons le gestionnaire de packages, puis nous verrons des exemples de mise en application.

PEAR est une initiative communautaire qui nous permet de réutiliser des composants de code PHP, tandis que le code dépendant est également ajouté et maintenu.

Tout d’abord, vous aurez besoin de PHP, ainsi que du gestionnaire de packages pour continuer. Il est préférable de les installer via Debian Advanced Package Manager (APT) si vous utilisez Linux.

Bien que PEAR soit une solution plus ancienne, elle est encore largement utilisée et est l’abréviation de PHP Extension and Application Repository. Selon la version de PHP installée, il est probable que PEAR soit déjà disponible. Vous pouvez vérifier en exécutant la commande pear sans arguments. Si vous recevez un avertissement indiquant que votre système ne l’a pas, exécutez simplement : sudo apt install php-pear. Nous sommes maintenant prêts à installer du code PHP tiers avec PEAR.

Si vous suivez cet article en faisant le codage en même temps, c’est à ce stade que vous devez ouvrir votre compte Mailgun pour avoir accès à l’API. Si vous êtes bloqué, consultez ces conseils de démarrage.

Les étapes avec PEAR s’appliquent de la manière suivante :

1. Installation des dépendances du projet et inclusion des packages en exigeant la classe principale ou le script vendor/autoloader.php
2. Fournir les identifiants liés à l’API, tels que votre clé API et les informations de votre domaine 
3. Instanciation du client ou de la classe Mail
4. Appel de fonction pour envoyer le ou les emails

C’est simple, n’est-ce pas ?

Nous pouvons installer le package Mail en tapant sudo pear install Mail à l’aide de la commande appropriée. Une fois l’installation terminée, l’étape suivante consiste à l’inclure dans un fichier de script au sein du répertoire de votre projet :

require_once "Mail.php";

Gagnez du temps et faites comme notre modèle le suggère, puis fournissez les variables spécifiques à l’API. 

Si vous vous rendez sur votre tableau de bord de l’API, vous trouverez ces informations nécessaires sous l’onglet du domaine :

Nous avons besoin des variables host, account user et password, ainsi que du port à utiliser :

Nous utilisons la connexion SMTP pour envoyer un email via notre compte Mailgun.

Nous rassemblons les paramètres ci-dessus dans un tableau et instancions la classe Mail avec ce qui suit :

La dernière étape consiste à appeler la méthode send() de la classe Mail et nous sommes prêts :

Ici, la variable $to contient la valeur de l’adresse du destinataire, tandis que la variable $headers est un tableau, contenant des champs supplémentaires pour la livraison.

À ce stade, vous voudrez peut-être consulter l’intégralité du code final :

Vous pouvez télécharger le code source complet ici.

Ensuite, si vous avez tout configuré, vous pouvez essayer d’exécuter le script : php mailer.php.

Vous l’exécutez, et vous recevez une horrible trace de pile d’erreur ! Examinez-la de plus près :

PHP Fatal error: Uncaught Error: Class 'Net_SMTP' not found in /usr/share/php/Mail/smtp>php:366.

Cela signifie que nous avons oublié d’ajouter une autre dépendance de projet nécessaire pour utiliser PEAR Mail. Exécutez sudo pear install Net_SMTP et réessayez !

La sortie est la suivante :

Message envoyé avec succès !

Si vous avez suivi ces étapes, votre message devrait être arrivé dans la messagerie spécifiée, et je vous applaudis silencieusement. Bravo ! 

La fonction native mail() de PHP permet d’envoyer des messages depuis votre application, mais elle présente des inconvénients. Parce qu’elle dépend de la configuration locale du serveur d’email, les emails envoyés de cette manière sont souvent interceptés par les filtres anti-spam ou bloqués purement et simplement. Elle manque également de fonctionnalités modernes essentielles comme le suivi, les statistiques, et des options de délivrabilité fiables. Plus grave encore, des implémentations naïves peuvent vous exposer à des attaques par injection d’en-tête. En résumé, la fonction mail() dépanne, mais pour des emails de production, il vous faudra une API dédiée comme le SDK PHP de Mailgun. 

• Délivrabilité : les messages dépendent de la configuration locale du serveur d’email, qui manque souvent d’un alignement approprié pour SPF, DKIM et DMARC. Cela diminue la réputation d’expéditeur et réduit le placement en boîte de réception. 
• Risque de spam : les emails provenant de serveurs web sont fréquemment signalés ou rejetés par des filtres qui se méfient des IP de serveurs génériques et de l’absence d’authentification. 
• Pas d’authentification SMTP : mail() ne supporte pas nativement le SMTP authentifié. Vous devez configurer manuellement ou utiliser une autre bibliothèque pour passer par un relais SMTP approprié. 
• Pas de suivi ni de statistiques : il n’y a aucun moyen intégré de suivre les ouvertures, les clics, les rebonds ou les plaintes, et aucun webhook d’événement pour une surveillance programmatique. 

Pour une livraison, une authentification et des statistiques fiables, utilisez un service dédié comme l’API PHP de Mailgun. 

Nous avons vu le script d’exemple pour commencer à utiliser Mailgun avec le gestionnaire de packages PEAR, et nous avons créé des scripts PHP pour envoyer un email avec le SMTP et l’API HTTP. L’intégration de tests appropriés garantit que votre livraison d’email fonctionne comme prévu. Cependant, d’autres options s’offrent à vous si PEAR n’est pas votre choix privilégié. Des alternatives comme SendGrid vous permettent d’obtenir le même résultat en utilisant Composer, et Mailgun a déjà détaillé ce point précédemment sur le blog. Pour des instructions plus approfondies, consultez notre tutoriel sur l’implémentation de l’API de Mailgun avec PHP. 

Et bien sûr, si vous souhaitez améliorer vos compétences avec PHP, voici quelques-unes de mes ressources préférées que je recommanderais pour envoyer un email avec PHP et gérer le format HTML pour l’email en général. 

Auteur·trice: Mailgun Community Stories from the Mailgun community