Como Instalar e Usar o MailHog com Laravel para Testes de Email

Por Paulo RB em 24/09/2024

No desenvolvimento de aplicações web, especialmente no Laravel, enviar emails é uma tarefa comum. Porém, testar o envio de emails em ambientes de desenvolvimento pode ser desafiador, já que você não quer correr o risco de enviar emails de teste para destinatários reais. É aí que o MailHog entra em cena. O MailHog é uma ferramenta simples e eficaz para capturar e visualizar emails enviados durante o desenvolvimento, garantindo que eles nunca sejam entregues a usuários reais. Neste artigo, vamos mostrar como instalar o MailHog e configurá-lo para uso com o Laravel.

O que é o MailHog?

O MailHog é um servidor de email local que captura e exibe emails enviados durante o desenvolvimento em uma interface web simples. Ele se conecta ao seu sistema como um servidor SMTP e armazena todos os emails que sua aplicação tenta enviar, evitando que eles cheguem a destinatários reais. Isso o torna uma ferramenta ideal para desenvolvimento e testes de email.

Como Instalar o MailHog

Instalando no Linux (ou WSL no Windows)

Se você está utilizando um sistema Linux ou o Windows Subsystem for Linux (WSL), instalar o MailHog é bem simples. A instalação pode ser feita diretamente utilizando o Go, já que o MailHog é uma aplicação Go(se você não tem o Go instalado veja este artigo: https://paulorb.dev/como-instalar-o-go-language-no-ubuntu/).

Certifique-se de que você tem o Go instalado no seu ambiente de desenvolvimento.

Execute o seguinte comando para instalar a versão mais recente do MailHog:

Copy Code

go install github.com/mailhog/MailHog@latest

Após a instalação, inicie o MailHog:

Copy Code

MailHog

4.O MailHog estará disponível no endereço http://localhost:8025, onde você poderá visualizar os emails capturados.

Configurando o Laravel para Usar o MailHog

Agora que o MailHog está instalado e rodando, vamos configurar o Laravel para utilizar o MailHog como o servidor SMTP de desenvolvimento.

Abra o arquivo .env na raiz do seu projeto Laravel.

Substitua as configurações de email para as seguintes:

Copy Code


MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS=example@example.com
MAIL_FROM_NAME="${APP_NAME}"

Essas configurações indicam que o Laravel deve usar o localhost como servidor SMTP, na porta 1025, que é a porta padrão do MailHog para capturar emails.

Testando o Envio de Emails

Para garantir que tudo está funcionando, vamos criar uma rota de teste no Laravel para enviar um email.
1. No arquivo routes/web.php, adicione o seguinte código:

Copy Code


use Illuminate\Support\Facades\Mail;

Route::get('/send-test-email', function () {
    Mail::raw('Este é um email de teste!', function ($message) {
        $message->to('teste@example.com')
                ->subject('Email de Teste');
    });

    return 'Email enviado!';
});

Agora, acesse a rota http://localhost:8000/send-test-email no seu navegador. Isso irá disparar o envio de um email de teste.
Acesse o MailHog em http://localhost:8025 para verificar se o email foi capturado. O email de teste deve aparecer na interface do MailHog.

Resolvendo Problemas Comuns

1. Erro: “Connection could not be established with host mailhog”

Este erro pode ocorrer se o Laravel não conseguir se conectar ao servidor MailHog. Para corrigir isso, verifique se você configurou o MAIL_HOST corretamente como localhost no arquivo .env. Além disso, certifique-se de que o MailHog está rodando na porta correta (1025).

Copy Code

MAIL_FROM_ADDRESS=example@example.com MAIL_FROM_NAME="Seu Nome ou Nome do Aplicativo"

2. Erro: “Cannot send message without a sender address”

Este erro indica que o endereço de remetente (MAIL_FROM_ADDRESS) não foi configurado. Certifique-se de que você adicionou a variável MAIL_FROM_ADDRESS ao seu arquivo .env:

Copy Code


Mail::raw('Este é um email de teste!', function ($message) {
    $message->to('destinatario@example.com')
            ->from('remetente@example.com', 'Nome do Remetente')
            ->subject('Email de Teste');
});

3. Erros ao Usar Docker

Se você estiver usando Docker, o erro de conexão pode ocorrer porque o nome do host está incorreto. No Docker, o MAIL_HOST deve ser o nome do serviço MailHog definido no arquivo docker-compose.yml.

No arquivo .env, ajuste o MAIL_HOST para o nome do serviço mailhog (caso esteja utilizando Docker):

Copy Code


MAIL_HOST=mailhog
MAIL_PORT=1025

No arquivo docker-compose.yml:

Copy Code

services: app: build: context: . environment: - MAIL_HOST=mailhog mailhog: image: mailhog/mailhog ports: - "8025:8025" - "1025:1025"

O MailHog é uma ferramenta essencial para o desenvolvimento de aplicações que enviam emails. Com ele, você pode capturar, visualizar e testar emails enviados durante o desenvolvimento sem o risco de enviá-los para destinatários reais. Integrá-lo ao Laravel é simples e eficaz, garantindo que seus testes de email sejam seguros e eficientes.

Se você está trabalhando em um ambiente de desenvolvimento onde o envio de emails precisa ser testado constantemente, o MailHog é uma excelente escolha. Com ele, você pode visualizar todos os emails enviados localmente de forma organizada, garantindo que suas funcionalidades de email estejam funcionando corretamente antes de colocar seu código em produção.

Agora que você já sabe como instalar e configurar o MailHog com Laravel, não deixe de utilizá-lo nos seus projetos para evitar surpresas indesejadas quando for realizar o envio de emails em produção.

Passo Extra:

Se o comando MailHog não funcionar de primeiro e você não quiser ou não puder usar o Go para instalar o MailHog, pode baixar o binário diretamente.