Symfony/Mailer para PHP: guía completa para enviar correos electrónicos

1. ¿Qué es y para qué sirve?

Symfony/Mailer es un componente potente y flexible del ecosistema Symfony, diseñado para enviar correos electrónicos desde aplicaciones PHP. A diferencia de la función nativa de PHP mail(), que requiere configurar manualmente cabeceras y tipos MIME, Symfony/Mailer ofrece una API orientada a objetos para crear, formatear y enviar mensajes a través de diversos transportes (SMTP, Sendmail, API de servicios externos).

El objetivo principal de esta librería es abstraer el proceso de envío de correos, permitiendo al desarrollador centrarse en el contenido del mensaje, no en los detalles de bajo nivel de los protocolos. Symfony/Mailer soporta plantillas HTML, archivos adjuntos, imágenes incrustadas, firma DKIM e integración con servicios de correo populares mediante Mailer DSN (Data Source Name).

Esta librería es indispensable para proyectos que requieren el envío confiable de correos transaccionales (confirmación de registro, restablecimiento de contraseña, notificaciones), campañas de marketing o cualquier otra notificación por email. Gracias a su arquitectura modular, Symfony/Mailer es fácil de probar (a través de MockTransport) y escalable.

2. Instalación

La instalación se realiza mediante Composer, el gestor de paquetes estándar para PHP. Ejecuta en la terminal, en la raíz de tu proyecto:

composer require symfony/mailer

Si usas Symfony Flex (recomendado), tras la instalación se creará automáticamente el archivo de configuración config/packages/mailer.yaml. Para trabajar con servicios de correo populares (SendGrid, Mailgun, Amazon SES, etc.), instala el adaptador correspondiente, por ejemplo:

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

También necesitarás el componente symfony/http-client para trabajar con transportes API:

composer require symfony/http-client

3. Inicio rápido — ejemplo mínimo funcional

Después de instalar la librería, puedes enviar tu primer correo en solo unas líneas. Crea un archivo enviar_correo.php:

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

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

// 1. Creamos el transporte (servidor SMTP de Gmail)
$transport = new EsmtpTransport('smtp.gmail.com', 587, true);
$transport->setUsername('tu-correo@gmail.com');
$transport->setPassword('tu-contraseña-app'); // Usa una contraseña de aplicación

// 2. Creamos el Mailer
$mailer = new Mailer($transport);

// 3. Creamos el correo
$email = (new Email())
    ->from('tu-correo@gmail.com')
    ->to('destinatario@ejemplo.com')
    ->subject('¡Saludos desde Symfony Mailer!')
    ->text('Este es un correo de prueba enviado con Symfony/Mailer.')
    ->html('<h1>¡Hola!</h1><p>Esta es la versión <strong>HTML</strong> del correo.</p>');

// 4. Enviamos
try {
    $mailer->send($email);
    echo "¡Correo enviado con éxito!\n";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Ejecuta el script:

php enviar_correo.php

Si todo está configurado correctamente, recibirás el correo en la dirección indicada.

4. Métodos y clases principales

4.1. Email::class — clase para crear el correo

Firma: new Email() (constructor sin parámetros)

Qué hace: Crea un objeto de correo con métodos setter para configurar todos los atributos (remitente, destinatario, asunto, cuerpo del mensaje, archivos adjuntos, etc.).

Ejemplo:

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('remitente@ejemplo.com')
    ->to('destinatario@ejemplo.com')
    ->cc('copia@ejemplo.com')
    ->bcc('copia-oculta@ejemplo.com')
    ->replyTo('responder-a@ejemplo.com')
    ->priority(Email::PRIORITY_HIGH)
    ->subject('Asunto del correo')
    ->text('Contenido en texto plano')
    ->html('<p>Contenido en HTML</p>');