Symfony/Mailer para PHP: guia completo de envio de e-mails

1. O que é e para que serve

Symfony/Mailer é um componente poderoso e flexível do ecossistema Symfony, projetado para enviar e-mails a partir de aplicações PHP. Diferente da função nativa do PHP mail(), que exige configuração manual de cabeçalhos e tipos MIME, o Symfony/Mailer oferece uma API orientada a objetos para criar, formatar e enviar mensagens através de diversos transportes (SMTP, Sendmail, API de serviços terceiros).

O principal objetivo da biblioteca é abstrair o processo de envio de e-mails, permitindo que o desenvolvedor foque no conteúdo da mensagem, e não nos detalhes de baixo nível dos protocolos. O Symfony/Mailer suporta templates HTML, anexos, incorporação de imagens, assinatura DKIM e integração com serviços populares de e-mail através do Mailer DSN (Data Source Name).

A biblioteca é indispensável para projetos que exigem envio confiável de e-mails transacionais (confirmação de cadastro, redefinição de senha, notificações), campanhas de marketing ou qualquer outro tipo de notificação por e-mail. Graças à sua arquitetura modular, o Symfony/Mailer é facilmente testável (via MockTransport) e escalável.

2. Instalação

A instalação é feita via Composer, o gerenciador de pacotes padrão do PHP. Execute no terminal, na raiz do seu projeto:

composer require symfony/mailer

Se você estiver usando o Symfony Flex (recomendado), o arquivo de configuração config/packages/mailer.yaml será criado automaticamente após a instalação. Para trabalhar com serviços de e-mail populares (SendGrid, Mailgun, Amazon SES, etc.), instale o adaptador correspondente, por exemplo:

composer require symfony/sendgrid-mailer
composer require symfony/mailgun-mailer
composer require symfony/amazon-mailer

Você também precisará do componente symfony/http-client para trabalhar com transportes via API:

composer require symfony/http-client

3. Início rápido — exemplo funcional mínimo

Após instalar a biblioteca, você pode enviar seu primeiro e-mail com apenas algumas linhas. Crie um arquivo enviar_email.php:

<?php
// enviar_email.php
require_once 'vendor/autoload.php';

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;
use Symfony\Component\Mime\Email;

// 1. Cria o transporte (servidor SMTP do Gmail)
$transport = new EsmtpTransport('smtp.gmail.com', 587, true);
$transport->setUsername('seu-email@gmail.com');
$transport->setPassword('sua-senha-de-app'); // Use uma senha de aplicativo

// 2. Cria o Mailer
$mailer = new Mailer($transport);

// 3. Cria o e-mail
$email = (new Email())
    ->from('seu-email@gmail.com')
    ->to('destinatario@exemplo.com')
    ->subject('Olá do Symfony Mailer!')
    ->text('Este é um e-mail de teste enviado com Symfony/Mailer.')
    ->html('<h1>Olá!</h1><p>Esta é a versão <strong>HTML</strong> do e-mail.</p>');

// 4. Envia
try {
    $mailer->send($email);
    echo "E-mail enviado com sucesso!\n";
} catch (\Exception $e) {
    echo "Erro: " . $e->getMessage() . "\n";
}

Execute o script:

php enviar_email.php

Se tudo estiver configurado corretamente, você receberá o e-mail no endereço indicado.

4. Principais métodos/classes

4.1. Email::class — classe para criar o e-mail

Assinatura: new Email() (construtor sem parâmetros)

O que faz: Cria um objeto de e-mail com métodos setters para configurar todos os atributos (remetente, destinatário, assunto, corpo do e-mail, anexos, etc.).

Exemplo:

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('remetente@exemplo.com')
    ->to('destinatario@exemplo.com')
    ->cc('copia@exemplo.com')
    ->bcc('copia-oculta@exemplo.com')
    ->replyTo('responder-para@exemplo.com')
    ->priority(Email::PRIORITY_HIGH)
    ->subject('Assunto do e-mail')
    ->text('Conteúdo em texto plano')
    ->html('<p>Conteúdo em <strong>HTML</strong></p>');