Drupal Symfony Mailer Lite
Un módulo ligero de envío de correo electrónico que aprovecha la biblioteca Symfony Mailer para enviar correos HTML y de texto plano a través de varios métodos de transporte, incluyendo SMTP, Sendmail y configuraciones DSN personalizadas.
symfony_mailer_lite
Instalar
composer require 'drupal/symfony_mailer_lite:^2.0'
Overview
Drupal Symfony Mailer Lite es una solución moderna de envío de correo electrónico para Drupal que reemplaza al módulo Swiftmailer obsoleto. Utiliza el componente Symfony Mailer para proporcionar una entrega de correo fiable con soporte para múltiples mecanismos de transporte.
El módulo ofrece una interfaz administrativa limpia para configurar transportes de correo, opciones de formato de mensajes y pruebas de entrega de correo. Soporta correos HTML con incrustación automática de CSS usando la biblioteca CssToInlineStyles, generación automática de alternativas en texto plano usando Html2Text, e incrustación de imágenes dentro del contenido del correo.
Las capacidades clave incluyen múltiples configuraciones de transporte (SMTP, Sendmail, PHP mail nativo, DSN y Null para pruebas), plantillas de correo personalizables con Twig, soporte de archivos adjuntos compatible con el módulo MimeMail, e integración perfecta con el módulo Mail System para enrutamiento flexible de correo.
Features
- Múltiples opciones de transporte de correo: SMTP con soporte TLS/SSL, Sendmail, función PHP mail nativa, cadenas DSN personalizadas y transporte Null para desarrollo/pruebas
- Soporte de correo HTML con incrustación automática de CSS - transforma hojas de estilo CSS externas en estilos en línea para mejor compatibilidad con clientes de correo
- Generación automática de alternativa en texto plano desde contenido HTML usando la biblioteca Html2Text para clientes de correo que no soportan HTML
- Soporte de imágenes incrustadas - permite incrustar imágenes directamente en correos usando la sintaxis 'image:path' con validación de seguridad
- Plantillas de correo personalizables usando Twig con soporte para anulaciones de plantillas específicas por módulo y por clave
- Soporte de archivos adjuntos compatible tanto con formato nativo como con formato de adjuntos de MimeMail
- Gestión de múltiples transportes con capacidad de establecer un transporte predeterminado y cambiar entre transportes por mensaje
- Funcionalidad de correo de prueba para verificar que la configuración de transporte funciona correctamente
- Soporte de migración desde el módulo Swiftmailer - importa automáticamente la configuración existente de Swiftmailer durante la instalación
- Configuración de conjunto de caracteres con soporte para numerosas codificaciones incluyendo UTF-8, ISO-8859-x y conjuntos de caracteres asiáticos
- Integración con el módulo Mail System para configuración flexible de formateador y remitente de correo
Use Cases
Envío de correos transaccionales vía SMTP
Configure un transporte SMTP con las credenciales de su proveedor de correo (ej., SendGrid, Mailgun, Amazon SES o su propio servidor SMTP). Establézcalo como predeterminado, luego configure Mail System para usar symfony_mailer_lite para los módulos deseados. Todos los correos salientes se enviarán a través de su servidor SMTP con autenticación adecuada y cifrado TLS.
Correo HTML con estilos CSS en línea
Cree una plantilla de correo personalizada en su tema como symfony-mailer-lite-email--mymodule.html.twig. Agregue una definición de biblioteca en libraries.yml de su tema que incluya archivos CSS. Referencie la biblioteca en theme.info.yml de su tema. El módulo buscará automáticamente el CSS de la biblioteca y lo incrustará en línea para máxima compatibilidad con clientes de correo.
Incrustación de imágenes en correos HTML
En el contenido del cuerpo de su correo, referencie imágenes usando el prefijo especial 'image:': <img src="image:/sites/default/files/logo.png">. El módulo valida que la imagen existe en el directorio de archivos públicos, luego la incrusta como adjunto CID, reemplazando el src con la referencia cid: apropiada.
Entorno de desarrollo con correos deshabilitados
Agregue un transporte Null y establézcalo como predeterminado en entornos de desarrollo. Todos los correos se procesarán pero no se enviarán realmente, permitiéndole probar la generación de correos sin enviar mensajes reales. Revise los logs para verificar el contenido del correo.
Uso de transportes de terceros de Symfony Mailer
Para servicios como Mailchimp Transactional, Postmark u otros proveedores con paquetes de Symfony Mailer, instale el paquete vía Composer y use el tipo de transporte DSN con la cadena DSN apropiada (ej., 'postmark://ID@default'). Esto da acceso a todo el ecosistema de Symfony Mailer.
Agregar adjuntos a correos programáticamente
Implemente hook_symfony_mailer_lite_attach() para agregar archivos adjuntos a correos salientes. Retorne un array de objetos de archivo con propiedades uri, filename y filemime. Alternativamente, pase adjuntos en el array $params['files'] o $params['attachments'] al llamar a MailManager::mail().
Migración desde Swiftmailer
Simplemente instale y habilite Symfony Mailer Lite mientras Swiftmailer aún está instalado. El módulo importa automáticamente su configuración de transporte de Swiftmailer (SMTP o Sendmail) y ajustes de mensaje. Luego actualice Mail System para usar symfony_mailer_lite en lugar de swiftmailer, y finalmente desinstale Swiftmailer.
Especificar transporte por correo
Al enviar correos programáticamente, puede especificar un transporte diferente agregando la clave 'symfony_mailer_lite_transport' al array del mensaje con el ID del transporte. Esto permite enrutar ciertos correos a través de diferentes transportes (ej., transaccionales vs marketing).
Tips
- Use la página de Prueba para verificar su configuración de transporte antes de depender de ella para correos críticos
- Para desarrollo, use el transporte Null para prevenir el envío accidental de correos mientras prueba la generación de correos
- Al usar SMTP con autenticación, almacene las credenciales de forma segura y considere usar variables de entorno vía anulaciones en settings.php
- Cree plantillas de correo específicas por módulo para personalizar el aspecto de correos de diferentes módulos sin afectar a otros
- El módulo soporta el componente Symfony Messenger para envío asíncrono de correo - instale symfony/messenger para sitios de alto volumen
- Revise los mensajes de log recientes de Drupal después de enviar correos de prueba para verificar la entrega exitosa o diagnosticar fallos
- Para máxima compatibilidad con clientes de correo, mantenga los correos HTML simples y confíe en la función de incrustación de CSS en lugar de diseños complejos
Technical Details
Admin Pages 4
/admin/config/system/symfony-mailer-lite/transport
Página principal de administración para gestionar transportes de correo. Lista todos los transportes configurados mostrando su tipo, etiqueta y estado predeterminado. Permite agregar nuevos transportes, editar existentes, establecer un transporte como predeterminado y eliminar transportes no predeterminados.
/admin/config/system/symfony-mailer-lite/transport/add/{plugin_id}
Formulario para agregar un nuevo transporte de correo. Los campos disponibles varían según el tipo de transporte seleccionado.
/admin/config/symfony-mailer-lite/message-settings
Configure las opciones predeterminadas de formato de mensaje incluyendo tipo de contenido, conversión de formato de texto, generación de texto plano y conjunto de caracteres.
/admin/config/system/symfony-mailer-lite/test
Envía un correo de prueba para verificar que el transporte de correo está configurado correctamente.
Permisos 1
Hooks 2
hook_symfony_mailer_lite_attach
Permite a los módulos agregar archivos adjuntos a correos salientes. Se llama durante el método mail() antes del envío.
hook_symfony_mailer_lite_transport_info_alter
Permite a los módulos alterar las definiciones de plugins de transporte antes de que se almacenen en caché.
Troubleshooting 6
Verifique que un transporte predeterminado esté configurado y establecido. Navegue a /admin/config/system/symfony-mailer-lite/transport y verifique que al menos un transporte esté marcado como 'Predeterminado'. También verifique que Mail System esté configurado para usar symfony_mailer_lite para el módulo de envío.
Verifique que el nombre de usuario y contraseña sean correctos. Algunos proveedores requieren contraseñas específicas de aplicación. Compruebe si su servidor SMTP requiere un puerto específico (587 para TLS, 465 para SSL, 25 para sin cifrar). Deshabilite temporalmente la verificación de par TLS para depurar certificados autofirmados.
Asegúrese de que su tema defina una biblioteca 'symfony_mailer_lite' con sus archivos CSS. El nombre de la biblioteca debe coincidir exactamente con 'nombredetema/symfony_mailer_lite'. El CSS de esta biblioteca se incrustará automáticamente en línea en correos HTML.
Las imágenes deben estar ubicadas dentro del directorio de archivos públicos. Las imágenes remotas o imágenes fuera del directorio público se rechazan por seguridad. Revise los logs de Drupal para errores de validación. Verifique que la ruta de la imagen use el formato correcto: image:/path/to/file.png
Verifique que 'Generar versión alternativa en texto plano' esté habilitado en Configuración de mensajes. Esto requiere el paquete Composer html2text/html2text. Compruebe que los correos se envíen como HTML (tipo de contenido text/html).
Este error aparece cuando no existen transportes activos o el transporte predeterminado ha sido eliminado. Cree un nuevo transporte y establézcalo como predeterminado. Si existen transportes, verifique que estén habilitados y que el ajuste default_transport en symfony_mailer_lite.settings apunte a un ID de transporte válido.
Security Notes 6
- El permiso 'administer symfony_mailer_lite configuration' está marcado como 'restringir acceso' debido a la naturaleza sensible de la configuración de transporte de correo incluyendo credenciales SMTP
- Las contraseñas SMTP se almacenan en configuración y pueden ser visibles para usuarios con permisos de exportación de configuración
- Las imágenes incrustadas se validan para asegurar que existen dentro del directorio de archivos públicos para prevenir ataques de traversal de rutas
- El transporte Sendmail valida el comando para prevenir ataques de inyección de comandos
- La verificación de par TLS está habilitada por defecto para conexiones SMTP - solo deshabilitar en entornos de desarrollo con certificados autofirmados
- Considere usar anulaciones específicas de entorno en settings.php para credenciales SMTP en lugar de almacenarlas en configuración exportable