Symfony Mailer

Symfony Mailer is the official email-sending component of the Symfony framework, providing a transport-agnostic API for composing and delivering messages. Transports are configured via simple DSN strings, letting an application switch between SMTP, sendmail, or any of the numerous third-party API-based transports (Mailgun, Postmark, SendGrid, and others via bridge packages) without changing application code.

Built on top of symfony/mime for message construction, Mailer adds failover and round-robin transport strategies for reliability, an event system for hooking into the send lifecycle, and optional integration with Symfony Messenger for asynchronously dispatching emails through a message queue instead of sending them inline.

What You Get

• A fluent Email message API (via symfony/mime) supporting text/HTML bodies, attachments, and headers
• DSN-based transport configuration (smtp://, sendmail://, or third-party API transports via bridge packages)
• Failover and round-robin transport wrappers for delivery reliability across multiple providers
• An event system (MessageEvent, EventListener/) for hooking into message preparation and sending
• Optional Symfony Messenger integration to send emails asynchronously through a message queue
• Twig integration (via symfony/twig-bridge) for rendering HTML email templates

Common Use Cases

• Sending transactional emails (password resets, order confirmations) from a Symfony or standalone PHP application
• Switching email providers (SMTP to a third-party API) by changing a DSN string rather than application code
• Queuing outbound email through Symfony Messenger to avoid blocking HTTP request/response cycles
• Building failover-resilient email delivery across multiple SMTP or API transports

Under The Hood

Architecture - The component centers on Mailer.php/MailerInterface.php, which accepts a TransportInterface implementation and an Envelope (sender/recipient metadata) to send a RawMessage. Transport/ contains the transport abstraction layer — AbstractTransportFactory, AbstractHttpTransport, AbstractApiTransport as base classes that concrete bridge packages (Mailgun, Postmark, etc.) extend — plus built-in SmtpTransportFactory-backed transports, FailoverTransport, and RoundRobinTransport for multi-transport reliability strategies. EventListener/ and Event/ implement the send-lifecycle hooks, and Messenger/ provides the SendEmailMessage integration for async dispatch via Symfony’s Messenger component.

Tech Stack - Requires PHP 8.4.1+ and depends on symfony/mime for message construction, egulias/email-validator for RFC-compliant address validation, psr/event-dispatcher and psr/log for its event and logging integration, and optionally symfony/http-client/symfony/messenger for HTTP-based transports and async dispatch respectively — all following PSR interfaces to stay framework-agnostic where reasonable.

Code Quality - As one of Symfony’s individually-released components (split from the symfony/symfony monorepo), it inherits Symfony’s strict backward-compatibility policy and semantic versioning discipline, with a Tests/ directory covering transports, DSN parsing, and message assembly. DataCollector/ provides Symfony profiler integration for debugging sent emails in development, showing attention to developer experience beyond the core sending logic.

API Design - The primary flow — Transport::fromDsn() then new Mailer($transport) then $mailer->send($email) — is deliberately terse for the common case, as shown directly in the README. The DSN-based transport configuration is the standout design choice: switching from SMTP to a hosted email API requires changing one string rather than any code, which is a significant developer-experience win for provider migrations.