Comment envoyer des emails avec Laravel et Mailgun

Que vous envoyiez des réinitialisations de mots de passe, des confirmations de commande ou des newsletters marketing, une livraison d’emails fiable est cruciale pour toute application Laravel. En combinant l’élégant système d’envoi de Laravel avec la puissante API d’email de Mailgun, vous avez l’assurance que vos messages importants atteignent la boîte de réception. 

Dans ce guide, nous vous accompagnerons dans le processus d’intégration de Mailgun avec Laravel, de la configuration initiale à l’envoi de votre premier email de bienvenue automatisé. Vous découvrirez également des fonctionnalités avancées telles que le suivi des emails, les pièces jointes et la gestion appropriée des erreurs. 

Avant de vous plonger dans l’intégration, assurez-vous d’avoir : 

• Des connaissances de base sur Laravel et PHP 
• PHP et Composer installés localement 
• Node.js et npm installés localement 
• Un éditeur de code (nous utiliserons Visual Studio Code) 
• Un compte Mailgun (nous vous aiderons à le configurer) 

Commençons par préparer vos identifiants Mailgun. Si ce n’est pas déjà fait, créez un compte gratuit sur notre page d’inscription. Après votre inscription, vous devrez activer votre compte via l’email de confirmation que nous vous enverrons. 

Depuis votre tableau de bord Mailgun, récupérez ces trois éléments essentiels :  

1. Votre domaine Mailgun : Accédez à Send > Sending > Domains et copiez votre nom de domaine. 

2. Votre clé API : Cliquez sur le menu déroulant de votre compte, sélectionnez API Security et créez une nouvelle clé API. 

Sur la page des clés API, créez une nouvelle clé API en cliquant sur le bouton « Add new key » et en fournissant la description de la clé dans la modale « New API Key ». Assurez-vous de copier la valeur de votre clé API, car vous ne pourrez la voir qu’une seule fois : 

3. Votre région : Consultez la barre de navigation supérieure pour confirmer si vous êtes dans la région EU ou US. 

4. Domaine sandbox : Enfin, puisque vous utiliserez votre domaine sandbox dans ce guide, assurez-vous de configurer les destinataires autorisés. Cela garantit que les emails envoyés depuis votre domaine sandbox ne sont livrés qu’aux destinataires que vous avez explicitement autorisés, car les domaines sandbox sont limités aux tests et restreints à des destinataires spécifiques. 

Vous pouvez le faire en accédant à la page Overview de votre domaine, en saisissant l’adresse email et en cliquant sur « Save Recipient » :

Une fois que vous avez tous les identifiants nécessaires depuis le tableau de bord Mailgun, il est temps de configurer Laravel pour utiliser Mailgun. Ici, vous allez créer une application Laravel et mettre à jour les variables d’environnement liées aux emails avec les valeurs que vous avez obtenues précédemment. Vous enverrez ensuite un email de bienvenue aux nouveaux utilisateurs.  

Pour ce faire, vous utiliserez le kit de démarrage Laravel Breeze pour configurer l’authentification dans votre application et utiliser la façade Mail pour ajouter la fonctionnalité d’envoyer un email à un nouvel utilisateur lors de son inscription. 

Pour créer une application Laravel, exécutez la commande suivante dans votre terminal : 

Bash

                                

                                    composer create-project laravel/laravel laravel-mailgun-demo rncd laravel-mailgun-demo rncomposer require laravel/breeze --dev rnphp artisan breeze:install 
                                
                            

À l’invite, utilisez les informations suivantes : 

• Quelle stack Breeze souhaitez-vous installer ? Blade with Alpine 
• Souhaitez-vous la prise en charge du mode sombre ? Non 
• Quel framework de test préférez-vous ? PHPUnit 

Une fois que tout est installé, assurez-vous de compiler les assets front-end de votre application :  

Bash 

                                

                                    npm install
                                
                            

Configuration des emails
Maintenant que vous avez une application Laravel fonctionnelle avec l’authentification configurée, vous pouvez mettre à jour les variables d’environnement liées aux emails. Ouvrez votre fichier .env et commentez MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, et MAIL_ENCRYPTION. 

Remplacez la valeur de MAIL_MAILER par mailgun pour configurer l’application afin qu’elle utilise le pilote Mailgun, et remplacez la valeur de MAIL_FROM_ADDRESS par votre adresse email. 

Ensuite, juste en dessous des variables d’environnement liées aux emails, ajoutez les variables d’environnement spécifiques à Mailgun suivantes et assurez-vous de remplacer les éléments de substitution par les valeurs réelles que vous avez obtenues depuis le tableau de bord Mailgun : 

                                

                                    MAILGUN_DOMAIN=<YOUR-MAILGUN-DOMAIN> rnMAILGUN_SECRET=<YOUR-MAILGUN-API-KEY> rnMAILGUN_ENDPOINT=api.mailgun.net 
                                
                            

Afin d’utiliser le pilote Mailgun pour envoyer des emails, vous devez installer le transport Symfony Mailgun Mailer : 

Bash 

                                

                                    composer require symfony/mailgun-mailer symfony/http-client
                                
                            

Mise à jour des fichiers de configuration
\nUne fois le transport installé, ouvrez votre fichier de configuration config/mail.php et ajoutez la configuration suivante au tableau des mailers pour configurer Mailgun comme l’un des mailers disponibles :

                                

                                    php rnCopy rn'mailgun' => [ rn   'transport' => 'mailgun' rn],
                                
                            

Ensuite, ajoutez le code suivant au fichier config/services.php pour configurer Mailgun : 

                                

                                    'mailgun' => [ rn   'domain' => env('MAILGUN_DOMAIN'), rn   'secret' => env('MAILGUN_SECRET'), rn   'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'), rn   'scheme' => 'https', rn], 
                                
                            

Ce code garantit que votre application Laravel dispose des identifiants et paramètres nécessaires pour communiquer avec l’API de Mailgun afin d’envoyer des emails. 

À ce stade, la configuration requise est terminée. Vous pouvez désormais vérifier que tout est configuré correctement à l’aide de Tinker. 

Pour lancer l’environnement Tinker, exécutez la commande suivante dans votre terminal : 

Bash

                                

                                    php artisan tinker
                                
                            

Pour envoyer un email de test, exécutez la commande suivante dans le terminal Tinker : 

                                

                                    Mail::raw('This email confirms that everything was set up correctly!', function ($message) { rn   $message->to('your@email.com') rn   ->subject('Testing Laravel + Mailgun'); rn}); 
                                
                            

Assurez-vous de remplacer par votre adresse email et de vérifier que l’adresse email est ajoutée en tant que destinataire autorisé. 

 Cette commande utilise la méthode raw de la façade Mail pour envoyer un email à l’adresse email fournie. 

À présent, consultez votre boîte de réception pour vous assurer que vous avez bien reçu un email : 

Pour simplifier le processus d’envoi d’emails, Laravel fournit des classes mailable qui vous permettent de définir et de structurer le contenu de vos emails. Les classes mailable facilitent la personnalisation de l’objet, de la mise en page et des données transmises à la vue de l’email. Ici, vous allez créer une classe mailable que vous utiliserez pour envoyer un email de bienvenue aux nouveaux utilisateurs.

Pour créer la classe mailable, exécutez la commande suivante dans votre terminal : 

Bash 

                                

                                    php artisan make:mail WelcomeMessage
                                
                            

Cette commande crée une classe mailable dans le fichier app/Mail/WelcomeMessage.php . Dans la classe mailable, vous devez accepter certaines données qui sont transmises lorsque cette classe est appelée. Vous pouvez le faire via la méthode __construct. Modifiez cette méthode comme illustré ici : 

                                

                                    public function __construct( rn   protected User $user, rn) {} 
                                
                            

Ensuite, dans la méthode envelope, vous pouvez configurer l’adresse d’expédition et l’objet de l’email. Dans cet exemple, vous ne configurerez que l’objet de l’email, car vous utilisez une adresse d’expédition globale dans le fichier config/mail.php. Modifiez la méthode envelope comme suit : 

                                

                                    public function envelope(): Envelope rn{ rn   return new Envelope( rn       subject: 'Welcome to Our Platform', rn   ); rn} 
                                
                            

Ensuite, dans la méthode content, vous devez définir la vue qui sera utilisée pour afficher le contenu de l’email et transmettre le nom de l’utilisateur à l’aide du paramètre with. Modifiez la méthode content comme ceci : 

                                

                                    public function content(): Content rn{ rn   return new Content( rn       view: 'emails.welcome', rn       with: [ rn           'name' => $this->user->name, rn       ], rn   ); rn} 
                                
                            

N’oubliez pas d’ajouter cette instruction use au fichier : 

Maintenant, vous devez créer la vue que vous avez définie précédemment. Créez un nouveau fichier nommé emails/welcome.blade.php dans le dossier resources/views et ajoutez le contenu suivant : 

HTML

                                

                                    <!DOCTYPE html> rn<html> rn    <head>               rn        <title>Welcome to Our Platform</title>               rn        <style> rn            body { rn                font-family: Arial, sans-serif; rn                background-color: #f4f4f4; rn                margin: 0; rn                padding: 20px; rn            } rnrn            .email-container { rn                background-color: #ffffff; rn                padding: 20px; rn                max-width: 600px; rn                margin: auto; rn                border-radius: 8px; rn                box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); rn            } rnrn            h1 { rn                color: #333333; rn                font-size: 24px; rn                margin-bottom: 20px; rn            } rnrn            p { rn                color: #555555; rn                font-size: 16px; rn                line-height: 1.5; rn            } rnrn            .footer { rn                margin-top: 20px; rn                font-size: 14px; rn                color: #777777; rn                text-align: center; rn            }                                           rn        </style>           rnrn    </head>       rn    <body>               rn        <div class="email-container">                       rn            <h1>Hello, {{ $name }}!</h1>                       rn            <p> rn                Thank you for signing up on our platform. We're excited to have rn                you on board.             rn            </p>                       rn            <p> rn                Feel free to explore our features, and let us know if you need rn                any assistance.             rn            </p>                       rn            <p>Best regards,<br />{{ config('app.name') }} Team</p>                       rnrn            <div class="footer">                               rn                <p> rn                    © {{ date('Y') }} {{ config('app.name') }}. All rights reserved.         rn                </p>                           rn            </div>                   rn        </div>           rn    </body> rn</html> 
                                
                            

Implémentation de l’email de bienvenue 

Le code ci-dessus affiche un simple message de bienvenue avec le nom de l’utilisateur. 

Ensuite, vous devez configurer le contrôleur qui gère l’inscription des utilisateurs pour envoyer un email aux nouveaux utilisateurs. Dans cette application, le contrôleur qui gère l’inscription des utilisateurs se trouve dans le fichier app/Http/Controllers/Auth/RegisteredUserController.php. Ouvrez ce fichier et, dans la méthode store, ajoutez ce code juste avant l’instruction return : 

                                

                                    Mail::to($user->email)->send(new WelcomeMessage($user)); 
                                
                            

Ce code utilise la façade Mail pour envoyer un email à l’utilisateur spécifié à l’aide de la classe mailable WelcomeMessage. 

N’oubliez pas d’ajouter ces instructions use au même fichier : 

Il est maintenant temps de tester si tout fonctionne comme prévu. Pour ce faire, lancez le serveur Laravel en utilisant la commande suivante : 

Bash 

                                

                                    php artisan serve
                                
                            

Accédez à http://localhost:8000/register dans votre navigateur, remplissez tous les détails, puis cliquez sur le bouton REGISTER :

Vous devriez recevoir un email de bienvenue dans votre boîte de réception : 

Cela confirme que tout fonctionne comme prévu. 

En intégrant Mailgun avec Laravel, vous accédez à des fonctionnalités plus avancées qui peuvent enrichir vos capacités en matière d’emails bien au-delà du simple envoi de messages basiques. Jetons un coup d’œil à certaines de ces fonctionnalités. 

Mailgun vous permet d’ajouter facilement des pièces jointes à vos emails, ce qui est une exigence courante pour l’envoi de factures, de rapports ou d’autres documents. Vous pouvez ajouter une pièce jointe aux emails à l’aide de la méthode attachments de votre classe mailable : 

                                

                                    public function attachments(): array rn{ rn   return [ rn       Attachment::fromPath('/path/to/file') rn       ->as('fileName.pdf') rn       ->withMime('application/pdf'), rn   ]; rn}
                                
                            

Vous pouvez également utiliser des pièces jointes intégrées dans vos modèles d’emails : 

HTML 

                                

                                    <body> rn   Sample image: rn   <img src="{{ $message->embed($pathToImage) }}" /> rn</body> 
                                
                            

Mailgun propose fonctionnalités de suivi des emails qui vous permettent de suivre des statistiques importantes, par exemple lorsque les utilisateurs ouvrent vos emails et cliquent sur les liens inclus. C’est utile pour vous assurer que vos emails parviennent bien à vos utilisateurs et qu’ils interagissent avec. 

Pour implémenter le suivi, vous devez configurer un webhook Mailgun ainsi qu’une route dédiée dans votre application Laravel qui recevra les appels de webhook depuis Mailgun. Vous pouvez ensuite utiliser les données reçues par le webhook pour suivre les emails envoyés depuis votre application. 

Mailgun prend en charge l’utilisation de les balises qui vous aident à regrouper les emails à des fins de reporting et de suivi. Vous pouvez ajouter des balises à votre email via la méthode envelope dans la classe mailable : 

                                

                                      public function envelope(): Envelope rn   { rn      return new Envelope( rn      subject: 'Welcome to Our Platform', rn      tags: ['welcome'], rn      ); rn   }
                                
                            

Lors de l’intégration de Laravel avec Mailgun, il est important de gérer les erreurs et de déboguer les problèmes efficacement pour garantir la fiabilité. Parmi les erreurs courantes que vous rencontrerez au cours du processus d’intégration, on peut citer : 

• Unauthorized : si les valeurs MAILGUN_DOMAIN, MAILGUN_SECRET et MAILGUN_ENDPOINT définies dans votre fichier .env sont incorrectes, Mailgun ne sera pas en mesure d’authentifier vos requêtes. Vous devez vérifier ces valeurs pour vous assurer qu’elles sont correctes. 
• Domain not verified : dans l’environnement de production, si vous essayez d’envoyer des emails depuis un domaine Mailgun qui n’a pas été vérifié, la requête échouera. Vous devez vérifier votre domaine en ajoutant les enregistrements DNS nécessaires (SPF et DKIM). 
• Domain is not allowed to send : lorsque vous utilisez des domaines sandbox, vous ne pouvez envoyer des emails qu’aux destinataires autorisés. Vous devez vous assurer que vos destinataires figurent sur la liste d’autorisation lors de tests avec un domaine sandbox. 

En cas d’erreur lors du processus d’envoi d’emails, elle est généralement consignée dans le fichier journal par défaut de Laravel situé dans storage/logs/laravel.log. Si vous souhaitez consigner manuellement des erreurs spécifiques liées à Mailgun, vous devez encapsuler la logique d’envoi d’emails dans un bloc try…catch pour vous aider à identifier les problèmes rapidement : 

De plus, Mailgun fournit un tableau de bord intuitif sur lequel vous pouvez surveiller et résoudre les problèmes de livraison d’emails. Parmi les fonctionnalités clés du tableau de bord Mailgun :
Journaux d’emails : Mailgun conserve des journaux détaillés de toute l’activité des emails, y compris les livraisons réussies, les rebonds, les ouvertures, les clics et les échecs. Vous pouvez filtrer et rechercher dans ces journaux pour identifier les livraisons échouées ou les erreurs. 

Messages d’erreur : pour les emails échoués, Mailgun consigne des messages d’erreur détaillés qui peuvent vous aider à comprendre pourquoi un email n’a pas été livré (par exemple, des destinataires non valides ou des problèmes DNS). 

Vous pouvez accéder à ces journaux et messages d’erreur sur la page Logs, accessible en accédant à Send > Sending > Logs sur le tableau de bord Mailgun. 

Quels sont les problèmes courants et les solutions pour l’envoi d’emails avec Mailgun et Laravel ? 

1. Erreurs d’authentification 

• Vérifiez vos identifiants Mailgun.
• Vérifiez que votre point de terminaison correspond à votre région.

2. Vérification du domaine 

• Assurez-vous que les enregistrements DNS sont correctement configurés.
• Vérifiez les paramètres SPF et DKIM.

3. Limites de la sandbox 

• Confirmez l’autorisation du destinataire.
• Vérifiez les limites d’envoi.

Accédez aux journaux détaillés via votre tableau de bord Mailgun : 

1. Accédez à Send > Sending > Logs. 
2. Examinez l’état de livraison.
3. Consultez les rapports de rebond.
4. Surveillez les statistiques d’engagement. 

Implémentez une gestion appropriée des erreurs : 

Bonnes pratiques Pour garantir une délivrabilité optimale : 

1. Séparez vos types d’emails 

• Utilisez des domaines différents pour les emails transactionnels et les emails de marketing.
• Implémentez une mise en file d’attente appropriée pour les envois en masse.

2. Surveillez vos statistiques 

• Suivez les taux de rebond.
• Surveillez les plaintes pour spam.
• Analysez les taux d’ouverture.

3. Maintenez l’hygiène de la liste 

• Nettoyage régulier des adresses non valides.
• Supprimez les abonnés non engagés.
• Gérez les rebonds de manière appropriée.

Vous maîtrisez les bases de l’intégration de Laravel et Mailgun. Prêt à passer au niveau supérieur ? Explorez : 

• La configuration de modèles d’emails 
• L’implémentation de contenu dynamique 
• Les fonctionnalités avancées de suivi 
• Les fonctionnalités d’A/B testing 

Prêt à envoyer des emails en toute confiance ? Créez un compte Mailgun et commencez vos envois. 

Auteur·trice: Kevin Kiman