Como enviar e-mails usando o Laravel e o Mailgun

Seja para enviar links de redefinição de senha, confirmações de pedidos ou newsletters de marketing, a entrega de e-mail confiável é essencial para qualquer aplicativo do Laravel. Ao combinar o elegante sistema de e-mail do Laravel com a poderosa API de e-mail do Mailgun, você pode garantir que as suas mensagens importantes cheguem à caixa de entrada. 

Neste guia, vamos detalhar o processo de integração do Mailgun com o Laravel, desde a configuração inicial até o envio do seu primeiro e-mail de boas-vindas automatizado. Você também aprenderá sobre recursos avançados, como rastreamento de e-mail, anexos e tratamento de erros adequado. 

Antes de se aprofundar na integração, certifique-se de ter: 

• Conhecimento básico sobre o Laravel e o PHP 
• PHP e Composer instalados localmente 
• Node.js e npm instalados localmente 
• Um editor de código (usaremos o Visual Studio Code) 
• Uma conta do Mailgun (ajudaremos com a configuração) 

Vamos começar preparando as suas credenciais do Mailgun. Se ainda não tiver feito isso, crie uma conta gratuita em nossa página de cadastro. Após se cadastrar, você precisará ativar a sua conta através do e-mail de confirmação que enviaremos. 

No painel do Mailgun, reúna estes três itens essenciais:  

1. Seu domínio do Mailgun: acesse “Enviar” > “Envio” > “Domínios” e copie o seu nome de domínio. 

2. Sua chave de API: clique no menu suspenso da sua conta, selecione “API Security” e crie uma nova chave de API. 

Na página de chaves de API, crie uma nova chave de API clicando no botão “Add new key” e fornecendo a descrição da chave no modal “New API Key”. Certifique-se de copiar o valor da sua chave de API, pois você só poderá vê-la uma vez: 

3. Sua região: verifique a barra de navegação superior para confirmar se você está na região da UE ou dos EUA. 

4. Domínio de sandbox: por fim, como você usará o seu domínio de sandbox neste guia, não se esqueça de configurar os destinatários autorizados. Isso garante que os e-mails enviados do seu domínio de sandbox sejam entregues apenas aos destinatários que você autorizou explicitamente, pois os domínios de sandbox são limitados a testes e restritos a destinatários específicos. 

Você pode fazer isso acessando a página “Overview” do seu domínio, inserindo o endereço de e-mail e clicando em “Save Recipient”:

Depois de obter todas as credenciais necessárias no painel do Mailgun, é hora de configurar o Laravel para usar o Mailgun. Aqui, você criará um aplicativo do Laravel e atualizará as variáveis de ambiente relacionadas a e-mail com os valores obtidos anteriormente. Em seguida, você enviará um e-mail de boas-vindas aos novos usuários.  

Para conseguir isso, você usará o kit de início do Laravel Breeze para configurar a autenticação no seu aplicativo e usar o Mail facade para adicionar a funcionalidade de enviar um e-mail a um novo usuário assim que ele se cadastrar. 

Para criar um aplicativo do Laravel, execute o seguinte comando no seu terminal: 

Bash

                                

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

Quando solicitado, use as seguintes informações: 

• Qual stack do Breeze você gostaria de instalar? Blade com Alpine 
• Você gostaria de suporte ao modo escuro? Não 
• Qual framework de testes você prefere? PHPUnit 

Depois que tudo estiver instalado, não se esqueça de compilar os ativos de front-end do seu aplicativo:  

Bash 

                                

                                    npm install
                                
                            

Como configurar os e-mails
Agora que você tem um aplicativo do Laravel funcional com a autenticação configurada, é possível atualizar as variáveis de ambiente relacionadas a e-mail. Abra o seu arquivo .env e comente MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, e MAIL_ENCRYPTION. 

Substitua o valor de MAIL_MAILER por mailgun para configurar o aplicativo a fim de usar o driver do Mailgun e substitua o valor de MAIL_FROM_ADDRESS pelo seu endereço de e-mail. 

Em seguida, logo abaixo das variáveis de ambiente relacionadas a e-mail, adicione as seguintes variáveis de ambiente específicas do Mailgun e não se esqueça de substituir os valores de placeholder pelos valores reais que você obteve no painel do Mailgun: 

                                

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

Para usar o driver do Mailgun a fim de enviar e-mails, é preciso instalar o Symfony Mailgun Mailer transport: 

Bash 

                                

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

Atualização dos arquivos de configuração
Assim que o transporte estiver instalado, abra o seu arquivo de configuração config/mail.php e adicione a seguinte configuração à matriz de mailers para configurar o Mailgun como um dos mailers disponíveis:

                                

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

Em seguida, adicione o seguinte código ao arquivo config/services.php para configurar o Mailgun: 

                                

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

Esse código garante que o seu aplicativo do Laravel tenha as credenciais e configurações necessárias para se comunicar com a API do Mailgun para enviar e-mails. 

Neste momento, a configuração necessária está concluída. Agora, você pode testar se tudo está configurado corretamente usando o Tinker. 

Para iniciar o ambiente do Tinker, execute o seguinte comando no seu terminal: 

Bash

                                

                                    php artisan tinker
                                
                            

Para enviar um e-mail de teste, execute o seguinte comando no terminal do 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}); 
                                
                            

Certifique-se de substituir pelo seu endereço de e-mail e verifique se o endereço de e-mail foi adicionado como um destinatário autorizado. 

 Esse comando usa o método raw do Mail facade para enviar um e-mail ao endereço de e-mail fornecido. 

Agora, verifique a sua caixa de entrada para ter certeza de que você recebeu um e-mail: 

Para simplificar o processo de envio de e-mails, o Laravel fornece classes mailable que permitem definir e estruturar o seu conteúdo de e-mail. As classes mailable facilitam a personalização do assunto, do layout e dos dados passados para a visualização do e-mail. Aqui, você criará uma classe mailable que usará para enviar um e-mail de boas-vindas para novos usuários.

Para criar a classe mailable, execute o seguinte comando no seu terminal: 

Bash 

                                

                                    php artisan make:mail WelcomeMessage
                                
                            

Esse comando cria uma classe mailable no arquivo app/Mail/WelcomeMessage.php . Na classe mailable, você precisa aceitar alguns dados que são passados quando essa classe é chamada. Você pode fazer isso por meio do método __construct. Modifique esse método conforme mostrado aqui: 

                                

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

Em seguida, no método envelope, você pode configurar o endereço do remetente e o assunto do e-mail. Neste exemplo, você só configurará o assunto do e-mail, pois está usando um endereço de remetente global no arquivo config/mail.php. Modifique o método envelope da seguinte forma: 

                                

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

Depois, no método content, você precisa definir a visualização que será usada para renderizar o conteúdo do e-mail e passar o nome do usuário por meio do parâmetro with. Modifique o método content assim: 

                                

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

Não se esqueça de adicionar esta declaração use ao arquivo: 

Agora, você precisa criar a visualização que definiu anteriormente. Crie um novo arquivo chamado emails/welcome.blade.php na pasta resources/views e adicione o seguinte conteúdo: 

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> 
                                
                            

Como implementar o e-mail de boas-vindas 

O código acima renderiza uma mensagem de boas-vindas simples com o nome do usuário. 

Em seguida, você precisa configurar o controlador que lida com o cadastro de usuários para enviar um e-mail aos novos usuários. Neste aplicativo, o controlador responsável pelo cadastro de usuários está no arquivo app/Http/Controllers/Auth/RegisteredUserController.php. Abra este arquivo e, no método store, adicione este código logo antes da declaração return: 

                                

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

Esse código usa o Mail facade para enviar um e-mail ao usuário especificado usando a classe mailable WelcomeMessage. 

Não se esqueça de adicionar estas declarações use ao mesmo arquivo: 

Agora é hora de testar se tudo está funcionando como o esperado. Para isso, execute o servidor do Laravel com o seguinte comando: 

Bash 

                                

                                    php artisan serve
                                
                            

Acesse http://localhost:8000/register no seu navegador, preencha todos os detalhes e clique no botão “REGISTER”:

Você deverá receber um e-mail de boas-vindas na sua caixa de entrada: 

Isso confirma que tudo está funcionando como o esperado. 

Ao integrar o Mailgun com o Laravel, você obtém acesso a recursos mais avançados que podem aprimorar os seus recursos de e-mail muito além do envio de mensagens básicas. Vamos dar uma olhada em alguns desses recursos. 

O Mailgun permite que você adicione facilmente anexos aos seus e-mails, o que é um requisito comum para o envio de faturas, relatórios ou outros documentos. Você pode adicionar um anexo aos e-mails usando o método attachments na sua 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}
                                
                            

Também é possível usar anexos in-line nos seus modelos de e-mail: 

HTML 

                                

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

O Mailgun oferece recursos de rastreamento de e-mail que permitem monitorar métricas importantes, como quando os usuários abrem os seus e-mails e clicam nos links anexados. Isso é útil para garantir que os seus e-mails estejam chegando à base de usuários e havendo interação. 

Para implementar o rastreamento, é preciso configurar um webhook do Mailgun e uma rota dedicada no seu aplicativo do Laravel que receberá chamadas de webhook do Mailgun. Você pode usar os dados recebidos do webhook para rastrear os e-mails enviados do seu aplicativo. 

O Mailgun é compatível com o uso de tags que ajudam a agrupar e-mails para fins de relatórios e rastreamento. É possível adicionar tags ao seu e-mail por meio do método envelope na classe mailable: 

                                

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

Ao integrar o Laravel ao Mailgun, é importante tratar os erros e depurar problemas de forma eficaz para garantir a confiabilidade. Alguns dos erros comuns que você encontrará durante o processo de integração incluem: 

• Não autorizado: se os valores MAILGUN_DOMAIN, MAILGUN_SECRET e MAILGUN_ENDPOINT definidos no seu arquivo .env estiverem incorretos, o Mailgun não poderá autenticar as suas solicitações. Você deve verificar esses valores novamente para ter certeza de que estão corretos. 
• Domínio não verificado: no ambiente de produção, se você tentar enviar e-mails de um domínio do Mailgun que não foi verificado, a solicitação falhará. Você precisará verificar seu domínio adicionando os registros de DNS necessários (SPF e DKIM). 
• O domínio não tem permissão de envio: ao usar domínios de sandbox, você só pode enviar e-mails para destinatários autorizados. Ao realizar testes com um domínio de sandbox, certifique-se de que os seus destinatários estejam na lista de permissões. 

Quando ocorre um erro durante o processo de envio de e-mail, ele normalmente é registrado no arquivo de log padrão do Laravel localizado em storage/logs/laravel.log. Se você quiser registrar manualmente erros específicos relacionados ao Mailgun, coloque a lógica de envio de e-mail em um bloco try…catch para ajudar na identificação rápida de problemas: 

Além disso, o Mailgun fornece um painel intuitivo no qual é possível monitorar e solucionar problemas de entrega de e-mail. Alguns dos principais recursos do painel do Mailgun incluem:
Logs de e-mail: o Mailgun mantém logs detalhados de todas as atividades de e-mail, incluindo entregas bem-sucedidas, devoluções, aberturas, cliques e falhas. Você pode filtrar e pesquisar esses logs para identificar quaisquer entregas que falharam ou erros. 

Mensagens de erro: para e-mails que falharam, o Mailgun registra mensagens de erro detalhadas, o que pode ajudar a entender por que um e-mail não foi entregue (como destinatários inválidos ou problemas de DNS). 

Você pode acessar esses logs e mensagens de erro na página “Logs”, que pode ser acessada em “Enviar” > “Envio” > “Logs” no painel do Mailgun. 

Quais são os problemas e soluções comuns ao enviar e-mail com o Mailgun e o Laravel? 

1. Erros de autenticação 

• Verifique suas credenciais do Mailgun.
• Verifique se o endpoint corresponde à sua região.

2. Verificação de domínio 

• Certifique-se de que os registros de DNS estejam configurados corretamente.
• Verifique as configurações de SPF e DKIM.

3. Limitações do sandbox 

• Confirme a autorização dos destinatários.
• Verifique os limites de envio.

Acesse os logs detalhados pelo painel do Mailgun: 

1. Acesse “Enviar” > “Envio” > “Logs”. 
2. Analise o status de entrega.
3. Verifique os relatórios de devolução.
4. Monitore as métricas de engajamento. 

Implemente o tratamento de erros adequado: 

Práticas recomendadas Para garantir a melhor entregabilidade: 

1. Separe os seus tipos de e-mail 

• Use domínios diferentes para e-mails transacionais e de marketing.
• Implemente a fila adequada para envios em massa.

2. Monitore as suas métricas 

• Rastreie as taxas de devolução.
• Monitore as reclamações de spam.
• Analise as taxas de abertura.

3. Mantenha a higienização da lista 

• Faça a limpeza regular de endereços inválidos.
• Remova os assinantes não engajados.
• Trate as devoluções de maneira adequada.

Você domina os conceitos básicos da integração do Laravel com o Mailgun. Tudo pronto para subir de nível? Explore: 

• Configuração de modelos de e-mail 
• Implementação de conteúdo dinâmico 
• Recursos de rastreamento avançados 
• Recursos de testes A/B 

Pronto para enviar e-mails com confiança? Cadastre-se no Mailgun e comece a enviar. 

Autor: Kevin Kiman