# symfony/mailer architecture

> Architecture diagram of the GitHub repository symfony/mailer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/symfony/mailer
- Repository: https://github.com/symfony/mailer

## Overview

##### Project type and purpose
- This is a Symfony “Mailer” component: an open-source PHP library whose sole responsibility is sending emails. It provides a Mailer API, multiple Transport implementations (SMTP, Sendmail, HTTP APIs, null, failover, round-robin, etc.), event hooks, and integration points (Twig templating, data collectors, commands).

##### File structure
- Top-level files and dirs:
- Mailer.php, MailerInterface.php, Transport.php – core entry points
- Transport/… – implementations and factories (AbstractTransport, SmtpTransport, SendmailTransport, NullTransport, FailoverTransport, RoundRobinTransport, AbstractHttpTransport, AbstractApiTransport, TransportFactoryInterface, Dsn parser)
- EventListener/… – listeners for DKIM, S/MIME signing, encryption, logging, messenger integration
- Envelope.php, DelayedEnvelope.php, SentMessage.php – message envelope abstractions
- Command/ – Symfony console command for testing mail sending
- DataCollector/ – profiler integration
- Tests/ – full PHPUnit suite
- Patterns & choices:
- Strategy: transport implementations behind TransportInterface
- Factory: AbstractTransportFactory + DSN-based factory
- Decorator/Composite: FailoverTransport, RoundRobinTransport wrap multiple transports
- Event-driven: EventDispatcher plus listeners for cross-cutting concerns (signing, logging, encryption)

##### README
- Shows how to build a Mailer with a Transport (from DSN), how to register EventListeners (e.g. MessageListener + Twig BodyRenderer), and how to send Email or TemplatedEmail.
- Mentions dependencies: symfony/mime, symfony/event-dispatcher, twig-bridge (optional).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client Code"]:::external

    %% Mailer API Layer
    subgraph "Mailer API" 
        Mailer["Mailer"]:::core
        MailerInterface["MailerInterface"]:::interface
    end

    %% Message & Envelope
    subgraph "Message Abstractions"
        Email["Email/Mime Object"]:::external
        Envelope["Envelope"]:::core
        DelayedEnvelope["DelayedEnvelope"]:::core
        SentMessage["SentMessage"]:::core
    end

    %% Transport Factory
    subgraph "Transport Factory"
        DSNParser["Dsn Parser"]:::interface
        TransportFactoryInterface["TransportFactoryInterface"]:::interface
        AbstractTransportFactory["AbstractTransportFactory"]:::interface
        NativeTransportFactory["NativeTransportFactory"]:::concrete
        NullTransportFactory["NullTransportFactory"]:::concrete
        SendmailTransportFactory["SendmailTransportFactory"]:::concrete
    end

    %% Transport Layer
    subgraph "Transport Layer"
        TransportInterface["TransportInterface"]:::interface

        subgraph "Composite Transports"
            FailoverTransport["FailoverTransport"]:::composite
            RoundRobinTransport["RoundRobinTransport"]:::composite
        end

        subgraph "Concrete Transports"
            SmtpTransport["SmtpTransport"]:::concrete
            EsmtpTransport["EsmtpTransport"]:::concrete
            EsmtpTransportFactory["EsmtpTransportFactory"]:::concrete
            SendmailTransport["SendmailTransport"]:::concrete
            NullTransport["NullTransport"]:::concrete
            AbstractHttpTransport["AbstractHttpTransport"]:::concrete
            AbstractApiTransport["AbstractApiTransport"]:::concrete
        end

        AbstractTransport["AbstractTransport"]:::interface
    end

    %% Event System
    subgraph "Event System"
        EventDispatcher["EventDispatcher"]:::event
        subgraph "Events"
            MessageEvent["MessageEvent"]:::event
            FailedMessageEvent["FailedMessageEvent"]:::event
            SentMessageEvent["SentMessageEvent"]:::event
            MessageEvents["MessageEvents"]:::event
        end
        subgraph "Event Listeners"
            MessageListener["MessageListener"]:::event
            EnvelopeListener["EnvelopeListener"]:::event
            DkimSignedMessageListener["DkimSignedMessageListener"]:::event
            SmimeSignedMessageListener["SmimeSignedMessageListener"]:::event
            SmimeEncryptedMessageListener["SmimeEncryptedMessageListener"]:::event
            SmimeCertRepo["SmimeCertificateRepositoryInterface"]:::interface
            MessageLoggerListener["MessageLoggerListener"]:::event
            MessengerTransportListener["MessengerTransportListener"]:::event
        end
    end

    %% CLI & Profiler
    subgraph "CLI & Profiler"
        MailerTestCommand["MailerTestCommand"]:::cli
        MessageDataCollector["MessageDataCollector"]:::data
    end

    %% Messenger Integration
    subgraph "Messenger Integration"
        SendEmailMessage["SendEmailMessage"]:::external
        MessageHandler["MessageHandler"]:::external
    end

    %% External Services
    subgraph "External Services"
        SMTPServer["SMTP Server"]:::external
        HTTPAPI["HTTP API Endpoint"]:::external
    end

    %% Relationships
    Client -->|"calls send() on"| Mailer
    Mailer -->|"implements"| MailerInterface
    Mailer -->|"wraps in"| Envelope
    Envelope -->|"may delay"| DelayedEnvelope
    Mailer -->|"dispatch PreSend"| EventDispatcher
    EventDispatcher -->|"handles"| MessageListener
    EventDispatcher --> EnvelopeListener
    EventDispatcher --> DkimSignedMessageListener
    EventDispatcher --> SmimeSignedMessageListener
    EventDispatcher --> SmimeEncryptedMessageListener
    EventDispatcher --> MessageLoggerListener
    EventDispatcher --> MessengerTransportListener
    Mailer -->|"dispatch PostSend"| EventDispatcher
    Mailer -->|"calls send() on"| TransportInterface
    TransportInterface --> AbstractTransport
    AbstractTransport --> SmtpTransport
    AbstractTransport --> SendmailTransport
    AbstractTransport --> NullTransport
    AbstractTransport --> AbstractHttpTransport
    AbstractTransport --> AbstractApiTransport
    TransportInterface --> FailoverTransport
    TransportInterface --> RoundRobinTransport
    SmtpTransport --> EsmtpTransport
    EsmtpTransportFactory --> SmtpTransport
    DSNParser --> TransportFactoryInterface
    TransportFactoryInterface --> AbstractTransportFactory
    AbstractTransportFactory --> NativeTransportFactory
    AbstractTransportFactory --> NullTransportFactory
    AbstractTransportFactory --> SendmailTransportFactory
    TransportInterface -->|"sends to"| SMTPServer
    AbstractHttpTransport -->|"calls"| HTTPAPI
    MailerTestCommand --> Mailer
    MessageDataCollector --> EventDispatcher
    MessengerTransportListener --> SendEmailMessage
    MessengerTransportListener --> MessageHandler

    %% Click Events
    click Mailer "https://github.com/symfony/mailer/blob/7.3/Mailer.php"
    click MailerInterface "https://github.com/symfony/mailer/blob/7.3/MailerInterface.php"
    click TransportInterface "https://github.com/symfony/mailer/blob/7.3/Transport/TransportInterface.php"
    click TransportFactoryInterface "https://github.com/symfony/mailer/blob/7.3/Transport/TransportFactoryInterface.php"
    click DSNParser "https://github.com/symfony/mailer/blob/7.3/Transport/Dsn.php"
    click AbstractTransport "https://github.com/symfony/mailer/blob/7.3/Transport/AbstractTransport.php"
    click FailoverTransport "https://github.com/symfony/mailer/blob/7.3/Transport/FailoverTransport.php"
    click RoundRobinTransport "https://github.com/symfony/mailer/blob/7.3/Transport/RoundRobinTransport.php"
    click SmtpTransport "https://github.com/symfony/mailer/blob/7.3/Transport/Smtp/SmtpTransport.php"
    click EsmtpTransport "https://github.com/symfony/mailer/blob/7.3/Transport/Smtp/EsmtpTransport.php"
    click EsmtpTransportFactory "https://github.com/symfony/mailer/blob/7.3/Transport/Smtp/EsmtpTransportFactory.php"
    click SendmailTransport "https://github.com/symfony/mailer/blob/7.3/Transport/SendmailTransport.php"
    click NullTransport "https://github.com/symfony/mailer/blob/7.3/Transport/NullTransport.php"
    click AbstractHttpTransport "https://github.com/symfony/mailer/blob/7.3/Transport/AbstractHttpTransport.php"
    click AbstractApiTransport "https://github.com/symfony/mailer/blob/7.3/Transport/AbstractApiTransport.php"
    click NativeTransportFactory "https://github.com/symfony/mailer/blob/7.3/Transport/NativeTransportFactory.php"
    click NullTransportFactory "https://github.com/symfony/mailer/blob/7.3/Transport/NullTransportFactory.php"
    click SendmailTransportFactory "https://github.com/symfony/mailer/blob/7.3/Transport/SendmailTransportFactory.php"
    click Envelope "https://github.com/symfony/mailer/blob/7.3/Envelope.php"
    click DelayedEnvelope "https://github.com/symfony/mailer/blob/7.3/DelayedEnvelope.php"
    click SentMessage "https://github.com/symfony/mailer/blob/7.3/SentMessage.php"
    click MessageEvent "https://github.com/symfony/mailer/blob/7.3/Event/MessageEvent.php"
    click FailedMessageEvent "https://github.com/symfony/mailer/blob/7.3/Event/FailedMessageEvent.php"
    click SentMessageEvent "https://github.com/symfony/mailer/blob/7.3/Event/SentMessageEvent.php"
    click MessageEvents "https://github.com/symfony/mailer/blob/7.3/Event/MessageEvents.php"
    click MessageListener "https://github.com/symfony/mailer/blob/7.3/EventListener/MessageListener.php"
    click EnvelopeListener "https://github.com/symfony/mailer/blob/7.3/EventListener/EnvelopeListener.php"
    click DkimSignedMessageListener "https://github.com/symfony/mailer/blob/7.3/EventListener/DkimSignedMessageListener.php"
    click SmimeSignedMessageListener "https://github.com/symfony/mailer/blob/7.3/EventListener/SmimeSignedMessageListener.php"
    click SmimeEncryptedMessageListener "https://github.com/symfony/mailer/blob/7.3/EventListener/SmimeEncryptedMessageListener.php"
    click SmimeCertRepo "https://github.com/symfony/mailer/blob/7.3/EventListener/SmimeCertificateRepositoryInterface.php"
    click MessageLoggerListener "https://github.com/symfony/mailer/blob/7.3/EventListener/MessageLoggerListener.php"
    click MessengerTransportListener "https://github.com/symfony/mailer/blob/7.3/EventListener/MessengerTransportListener.php"
    click MessageDataCollector "https://github.com/symfony/mailer/blob/7.3/DataCollector/MessageDataCollector.php"
    click MailerTestCommand "https://github.com/symfony/mailer/blob/7.3/Command/MailerTestCommand.php"
    click SendEmailMessage "https://github.com/symfony/mailer/blob/7.3/Messenger/SendEmailMessage.php"
    click MessageHandler "https://github.com/symfony/mailer/blob/7.3/Messenger/MessageHandler.php"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef interface fill:#bbf,stroke:#333,stroke-width:1px
    classDef concrete fill:#bfb,stroke:#333,stroke-width:1px
    classDef composite fill:#fbf,stroke:#333,stroke-width:1px
    classDef event fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef cli fill:#ffe,stroke:#333,stroke-width:1px
    classDef data fill:#eef,stroke:#333,stroke-width:1px
```
