Cómo enviar emails usando Laravel y Mailgun

Ya estés enviando emails para restablecer contraseñas, confirmaciones de pedido o newsletters de marketing, una entrega de emails fiable es crucial para cualquier aplicación de Laravel. Al combinar el elegante sistema de envío de Laravel con la potente API de email de Mailgun, puedes garantizar que tus mensajes importantes lleguen a la bandeja de entrada. 

En esta guía, repasaremos el proceso de integración de Mailgun con Laravel, desde la configuración inicial hasta el envío de tu primer email de bienvenida automatizado. También aprenderás sobre funciones avanzadas como el seguimiento de emails, los adjuntos y la correcta gestión de errores. 

Antes de entrar de lleno en la integración, asegúrate de tener: 

• Conocimientos básicos de Laravel y PHP 
• PHP y Composer instalados a nivel local 
• Node.js y npm instalados a nivel local 
• Un editor de código (usaremos Visual Studio Code) 
• Una cuenta de Mailgun (te ayudaremos a configurarla) 

Empecemos por preparar tus credenciales de Mailgun. Si aún no lo has hecho, crea una cuenta gratuita en nuestra página de registro. Tras el registro, deberás activar tu cuenta a través del email de confirmación que te enviaremos. 

Desde tu panel de control de Mailgun, recopila estos tres elementos esenciales:  

1. Tu dominio de Mailgun: Ve a “Send > Sending > Domains” y copia tu nombre de dominio. 

2. Tu clave de API: Haz clic en el menú desplegable de tu cuenta, selecciona “Seguridad de la API” (“API Security”) y crea una nueva clave de API. 

En la página de claves de API, crea una nueva clave de API haciendo clic en el botón “Añadir nueva clave” y proporcionando la descripción en la ventana modal “Nueva clave de API”. Asegúrate de copiar el valor de tu clave de API, ya que solo podrás verla una vez: 

3. Tu región: Comprueba la barra de navegación superior para confirmar si estás en la región de la UE o de EE. UU. 

4. Dominio sandbox: Por último, dado que usarás tu dominio sandbox en esta guía, asegúrate de configurar los destinatarios autorizados. Esto garantiza que los emails enviados desde tu dominio sandbox solo se entreguen a los destinatarios que hayas autorizado explícitamente, ya que los dominios sandbox están limitados a las pruebas y restringidos a destinatarios específicos. 

Puedes hacerlo yendo a la página de información general (“Overview”) de tu dominio, introduciendo la dirección de email y haciendo clic en “Guardar destinatario” (“Save Recipient”):

Cuando tengas todas las credenciales necesarias del panel de control de Mailgun, será el momento de configurar Laravel para utilizar Mailgun. Aquí, crearás una aplicación de Laravel y actualizarás las variables de entorno relacionadas con el email con los valores que has obtenido antes. Luego enviarás un email de bienvenida a los nuevos usuarios.  

Para lograrlo, usarás el kit de inicio de Laravel Breeze para configurar la autenticación en tu aplicación y usar la fachada Mail para añadir la funcionalidad de enviar un email a un usuario nuevo cuando se registre. 

Para crear una aplicación de Laravel, ejecuta el siguiente comando en tu terminal: 

Bash

                                

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

Cuando se te pida, usa la siguiente información: 

• ¿Qué stack de Breeze quieres instalar? Blade con Alpine 
• ¿Quieres habilitar el modo oscuro? No 
• ¿Qué framework de pruebas prefieres? PHPUnit 

Una vez que todo esté instalado, asegúrate de compilar los recursos de frontend de tu aplicación:  

Bash 

                                

                                    npm install
                                
                            

Configuración del email
\nAhora que tienes una aplicación de Laravel funcional con la autenticación configurada, puedes actualizar las variables de entorno relacionadas con el email. Abre tu archivo .env y comenta MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, y MAIL_ENCRYPTION. 

Sustituye el valor de MAIL_MAILER por mailgun para configurar la aplicación para usar el controlador de Mailgun, y sustituye el valor de MAIL_FROM_ADDRESS por tu dirección de email. 

A continuación, justo debajo de las variables de entorno relacionadas con el email, añade las siguientes variables de entorno específicas de Mailgun y asegúrate de sustituir los marcadores de posición con los valores reales que has obtenido en el panel de control de Mailgun: 

                                

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

Para utilizar el controlador de Mailgun para enviar emails, debes instalar el transport Symfony Mailgun Mailer: 

Bash 

                                

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

Actualización de archivos de configuración
Una vez instalado el transport, abre el archivo de configuración config/mail.php y añade la siguiente configuración al array de mailers para configurar Mailgun como uno de los sistemas disponibles:

                                

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

A continuación, añade el siguiente código al archivo config/services.php para configurar Mailgun: 

                                

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

Este código garantiza que tu aplicación de Laravel tenga las credenciales y ajustes necesarios para comunicarse con la API de Mailgun y enviar emails. 

Llegados a este punto, la configuración necesaria se ha completado. Ahora, puedes comprobar que todo está configurado correctamente utilizando Tinker. 

Para iniciar el entorno Tinker, ejecuta el siguiente comando en tu terminal: 

Bash

                                

                                    php artisan tinker
                                
                            

Para enviar un email de prueba, ejecuta el siguiente comando en el terminal de 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}); 
                                
                            

Asegúrate de sustituir por tu dirección de email y comprueba que se haya añadido como destinatario autorizado. 

 Este comando utiliza el método raw de la fachada Mail para enviar un email a la dirección proporcionada. 

Ahora, revisa tu bandeja de entrada para asegurarte de que has recibido un email: 

Para simplificar el proceso de envío de emails, Laravel proporciona clases “mailable” que te permiten definir y estructurar el contenido de tu email. Las clases “mailable” facilitan la personalización del asunto, el diseño y los datos pasados a la vista del email. Aquí crearás una clase “mailable” que utilizarás para enviar un email de bienvenida a los nuevos usuarios.

Para crear la clase “mailable”, ejecuta el siguiente comando en tu terminal: 

Bash 

                                

                                    php artisan make:mail WelcomeMessage
                                
                            

Este comando crea una clase “mailable” en el archivo app/Mail/WelcomeMessage.php . En la clase “mailable”, deberás aceptar algunos de los datos que se pasan cuando se la llama. Puedes hacerlo a través del método __construct. Modifica este método tal y como se muestra a continuación: 

                                

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

A continuación, en el método envelope, puedes configurar la dirección del remitente y el asunto del email. En este ejemplo, solo vas a configurar el asunto del email, puesto que usas una dirección de remitente global en el archivo config/mail.php. Modifica el método envelope de esta manera: 

                                

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

A continuación, en el método content, debes definir la vista que se usará para renderizar el contenido del email y pasar el nombre del usuario con el parámetro with. Modifica el método content de la siguiente manera: 

                                

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

Recuerda añadir esta declaración “use” al archivo: 

Ahora tienes que crear la vista que has definido previamente. Crea un archivo nuevo llamado emails/welcome.blade.php en la carpeta resources/views y añade el siguiente contenido: 

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> 
                                
                            

Implementación del email de bienvenida 

Lo anterior renderiza un mensaje de bienvenida sencillo con el nombre del usuario. 

A continuación, tienes que configurar el controlador que gestiona el registro de usuarios para que envíe un email a los nuevos usuarios. En esta aplicación, el controlador que gestiona el registro de usuarios se encuentra en el archivo app/Http/Controllers/Auth/RegisteredUserController.php. Abre este archivo y en el método store añade este código justo antes de la declaración return: 

                                

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

Este código utiliza la fachada Mail para enviar un email al usuario especificado mediante la clase “mailable” WelcomeMessage. 

Recuerda añadir estas declaraciones “use” al mismo archivo: 

Ahora toca comprobar si todo funciona como está previsto. Para ello, ejecuta el servidor de Laravel mediante el siguiente comando: 

Bash 

                                

                                    php artisan serve
                                
                            

Ve a http://localhost:8000/register en tu navegador, rellena todos los datos y haz clic en el botón REGISTER:

Deberías recibir un email de bienvenida en tu bandeja de entrada: 

Esto confirma que todo funciona como está previsto. 

Al integrar Mailgun con Laravel, tienes acceso a funciones más avanzadas que pueden mejorar tus capacidades de email más allá del simple envío de mensajes básicos. Echemos un vistazo a algunas de estas funciones. 

Mailgun te permite añadir fácilmente archivos adjuntos a tus emails, lo cual es un requisito común a la hora de enviar facturas, informes u otros documentos. Puedes añadir un adjunto a los emails con el método attachments en tu clase “mailable”: 

                                

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

También puedes usar archivos adjuntos integrados (inline) en tus plantillas de email: 

HTML 

                                

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

Mailgun ofrece funciones de seguimiento de email que te permiten hacer un seguimiento de métricas importantes, como cuándo abren los usuarios tus emails y hacen clic en los enlaces incluidos. Esto es muy útil para comprobar que los usuarios reciben tus emails e interactúan con ellos. 

Para implementar el seguimiento, es necesario configurar un webhook de Mailgun y una ruta dedicada en tu aplicación de Laravel que recibirá las llamadas del webhook desde Mailgun. A continuación, puedes utilizar los datos recibidos del webhook para hacer un seguimiento de los emails enviados desde tu aplicación. 

Mailgun es compatible con el uso de etiquetas que te ayudan a agrupar los emails con fines de seguimiento e informes. Puedes añadir etiquetas a tu email a través del método envelope en la clase “mailable”: 

                                

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

Al integrar Laravel con Mailgun, es importante gestionar los errores y depurar los problemas de forma eficaz para garantizar la fiabilidad. Algunos de los errores más comunes que te encontrarás durante el proceso de integración son: 

• No autorizado (Unauthorized): si los valores MAILGUN_DOMAIN, MAILGUN_SECRET y MAILGUN_ENDPOINT definidos en tu archivo .env son incorrectos, Mailgun no podrá autenticar tus solicitudes. Te aconsejamos volver a comprobar estos valores para asegurarte de que son correctos. 
• Dominio no verificado (Domain not verified): en el entorno de producción, si intentas enviar emails desde un dominio de Mailgun que no ha sido verificado, la solicitud fallará. Es necesario que verifiques tu dominio añadiendo los registros DNS necesarios (SPF y DKIM). 
• El dominio no tiene permiso para realizar envíos (Domain is not allowed to send): al utilizar dominios sandbox, solo puedes enviar emails a destinatarios autorizados. Debes asegurarte de que tus destinatarios están en la lista de permitidos cuando hagas pruebas con un dominio sandbox. 

Cuando se produce un error durante el proceso de envío del email, normalmente se registra en el archivo de registro predeterminado de Laravel, ubicado en storage/logs/laravel.log. Si deseas registrar manualmente errores específicos relacionados con Mailgun, debes englobar la lógica de envío de emails en un bloque try…catch para que te ayude a identificar problemas rápidamente: 

Además, Mailgun proporciona un panel de control intuitivo en el que puedes hacer un seguimiento y solucionar los problemas de entrega de emails. El panel de control de Mailgun incluye funciones clave como estas:
Registros de email (Email logs): Mailgun conserva registros detallados de toda la actividad de los emails, lo que incluye entregas correctas, rebotes, aperturas, clics y fallos. Puedes aplicar filtros y buscar en estos registros para identificar cualquier error o fallo de entrega. 

Mensajes de error (Error messages): para los emails fallidos, Mailgun registra mensajes de error detallados que pueden ayudarte a entender por qué no se entregó el email (como en el caso de problemas de DNS o destinatarios no válidos). 

Puedes acceder a estos mensajes de error y registros en la página Logs (Registros), que encontrarás yendo a Send > Sending > Logs en el panel de control de Mailgun. 

¿Cuáles son los problemas más comunes y las soluciones al enviar emails con Mailgun y Laravel? 

1. Errores de autenticación 

• Comprueba tus credenciales de Mailgun.
• Verifica que el punto de conexión coincida con tu región.

2. Verificación de dominio 

• Asegúrate de que los registros DNS estén configurados correctamente.
• Verifica los ajustes de SPF y DKIM.

3. Limitaciones de sandbox 

• Confirma la autorización de los destinatarios.
• Comprueba los límites de envío.

Accede a registros detallados a través de tu panel de control de Mailgun: 

1. Ve a Send > Sending > Logs. 
2. Revisa el estado de la entrega.
3. Comprueba los informes de rebotes.
4. Supervisa las métricas de interacción. 

Implementa una correcta gestión de errores: 

Mejores prácticas Para garantizar una entregabilidad óptima: 

1. Separa tus tipos de email 

• Utiliza dominios diferentes para los emails transaccionales y de marketing.
• Implementa un proceso de encolado adecuado para los envíos masivos.

2. Supervisa tus métricas 

• Haz un seguimiento de las tasas de rebote.
• Supervisa las quejas por spam.
• Analiza las tasas de apertura.

3. Mantén la higiene de listas 

• Limpieza periódica de direcciones no válidas.
• Elimina a los suscriptores que no interactúan.
• Gestiona los rebotes adecuadamente.

Ya dominas los aspectos básicos de la integración de Mailgun con Laravel. ¿Quieres pasar al siguiente nivel? Explora: 

• Configuración de plantillas de email 
• Implementación de contenido dinámico 
• Funciones de seguimiento avanzadas 
• Capacidades de test A/B 

¿Todo listo para enviar emails con total confianza? Crea una cuenta de Mailgun y empieza a realizar envíos. 

Autor: Kevin Kiman