Symfony Mailer

https://github.com/symfony/mailer
Admin
Symfony Mailer is a component that helps sending emails with support for multiple transports,...
Tokens:37,395
Snippets:484
Trust Score:9.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Complete MessageListener Configuration Example

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Full setup including Twig rendering, custom header rules, and templated email dispatch.

```php
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Twig
use Twig

// Setup Twig
$twig = new Environment(new FileSystemLoader('./templates'));

// Setup headers to inject
$headers = new Headers();
$headers->addTextHeader('X-Mailer', 'MyApp Mailer');
$headers->addTextHeader('X-Priority', '3');

// Setup template renderer
$renderer = new BodyRenderer($twig);

// Create listener with headers and renderer
$listener = new MessageListener($headers, $renderer);

// Customize rules
$listener->addHeaderRule('x-custom', MessageListener::HEADER_REPLACE);

// Setup dispatcher with listener
$dispatcher = new EventDispatcher();
$dispatcher->addSubscriber($listener);

// Create mailer
$transport = Transport::fromDsn('smtp://localhost', $dispatcher);
$mailer = new Mailer($transport, null, $dispatcher);

// Send templated email
$email = (new TemplatedEmail())
    ->from('noreply@example.com')
    ->to('user@example.com')
    ->subject('Welcome!')
    ->htmlTemplate('emails/welcome.html.twig')
    ->context(['name' => 'John']);

$mailer->send($email);
// Listener automatically:
// 1. Injects X-Mailer and X-Priority headers
// 2. Renders Twig template with context
// 3. Sets rendered HTML/text as message body
```

--------------------------------

### Complete Mailer Example with Headers

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/headers.md

A full example demonstrating transport configuration and the addition of both tags and metadata.

```php
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Header\TagHeader;
use Symfony\Component\Mailer\Header\MetadataHeader;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mime\Email;

$transport = Transport::fromDsn('postmark+api://token@default');
$mailer = new Mailer($transport);

$email = (new Email())
    ->from('noreply@example.com')
    ->to('customer@example.com')
    ->subject('Your Order #12345');

// Add tags for filtering and analytics
$email->getHeaders()->add(new TagHeader('order-confirmation'));
$email->getHeaders()->add(new TagHeader('transactional'));

// Add metadata for webhook processing
$email->getHeaders()->add(new MetadataHeader('order_id', '12345'));
$email->getHeaders()->add(new MetadataHeader('customer_id', 'cust_xyz'));
$email->getHeaders()->add(new MetadataHeader('store_location', 'Downtown'));

$email->text('Your order has been confirmed.');

$mailer->send($email);
// Headers are preserved and sent to the provider
```

--------------------------------

### Sendmail Transport Example

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Example of configuring the sendmail binary path and flags.

```text
sendmail:///usr/sbin/sendmail?command=/usr/sbin/sendmail%20-oi%20-t
```

--------------------------------

### Install Symfony Mailer

Source: https://github.com/symfony/mailer/blob/8.2/README.md

Install the Mailer component using Composer. This is the first step to start sending emails with Symfony.

```bash
composer require symfony/mailer
```

--------------------------------

### Common DSN Examples

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/quick-start.md

Examples of DSN strings for various transport types and configurations.

```php
// Local SMTP
'smtp://localhost'

// SMTP with auth and TLS
'smtp://user:pass@smtp.example.com:587?encryption=tls'

// SMTP over SSL (port 465)
'smtps://user:pass@smtp.gmail.com:465'

// SendGrid
'sendgrid+api://YOUR_SENDGRID_API_KEY@default'

// Mailgun
'mailgun+api://YOUR_DOMAIN_NAME:YOUR_MAILGUN_API_KEY@default'

// Failover
'failover(sendgrid+api://key1@default mailgun+api://domain@key2)'

// Round-robin
'roundrobin(smtp://host1 smtp://host2 smtp://host3)'
```

--------------------------------

### Usage examples for fromDsns()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Demonstrates initializing multiple transports and selecting one via the X-Transport header.

```php
$transports = Transport::fromDsns([
    'primary' => 'smtp://smtp1.example.com',
    'backup' => 'smtp://smtp2.example.com',
]);

// Messages can specify transport via X-Transport header
$email->getHeaders()->addTextHeader('X-Transport', 'primary');
```

--------------------------------

### Direct Mailer Instantiation

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sendmail-transport.md

Example of manually instantiating the transport and passing it to the Mailer service.

```php
use Symfony\Component\Mailer\Transport\SendmailTransport;
use Symfony\Component\Mailer\Mailer;

$transport = new SendmailTransport('/usr/sbin/sendmail -bs');
$mailer = new Mailer($transport);

$mailer->send($email);
```

--------------------------------

### DSN Configuration Examples

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/README.md

Common DSN formats for configuring mailer transports, including standard SMTP, secure SMTP, API-based services, and composite failover setups.

```text
scheme://[user[:password]@]host[:port][?options]
```

```text
smtp://localhost:25
smtps://user:pass@smtp.gmail.com:465
sendgrid+api://api-key@default
failover(smtp://host1 smtp://host2)
```

--------------------------------

### MetadataHeader Provider Usage

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/headers.md

Examples of using metadata for webhook context and tracking.

```php
// Store context for webhook processing
$email->getHeaders()->add(new MetadataHeader('user_id', $userId));
$email->getHeaders()->add(new MetadataHeader('event_type', 'account_created'));
$email->getHeaders()->add(new MetadataHeader('campaign', 'onboarding_flow'));
```

--------------------------------

### Initialize RoundRobinTransport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/roundrobin-failover.md

Examples of creating a RoundRobinTransport instance with DSNs and custom retry settings.

```php
use Symfony\Component\Mailer\Transport\RoundRobinTransport;
use Symfony\Component\Mailer\Transport;

$transport = new RoundRobinTransport([
    Transport::fromDsn('smtp://smtp1.example.com'),
    Transport::fromDsn('smtp://smtp2.example.com'),
    Transport::fromDsn('smtp://smtp3.example.com'),
]);

// Retry dead transports after 120 seconds
$transport = new RoundRobinTransport($transports, 120, $logger);
```

--------------------------------

### Usage examples for fromDsn()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Demonstrates creating SMTP transports with various configurations including authentication and event dispatching.

```php
use Symfony\Component\Mailer\Transport;
use Symfony\Component\EventDispatcher\EventDispatcher;

// SMTP transport
$transport = Transport::fromDsn('smtp://localhost:25');

// SMTP with TLS
$transport = Transport::fromDsn('smtps://user:pass@smtp.gmail.com:465');

// With event dispatcher
$dispatcher = new EventDispatcher();
$transport = Transport::fromDsn('smtp://localhost', $dispatcher);
```

--------------------------------

### Instantiating SendmailTransport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sendmail-transport.md

Examples showing default initialization, custom binary paths, and batch mode configuration.

```php
use Symfony\Component\Mailer\Transport\SendmailTransport;

// Default interactive mode
$transport = new SendmailTransport();

// Custom sendmail location
$transport = new SendmailTransport('/usr/local/sbin/sendmail -bs');

// Batch mode with additional flags
$transport = new SendmailTransport('/usr/sbin/sendmail -oi -t');
```

--------------------------------

### Complete Async Mailer Setup

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/messenger.md

Manually instantiate the mailer, message bus, and handler to enable asynchronous email queuing.

```php
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Messenger\MessageHandler;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Messenger\Handler\HandlerResolver;
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;
use Symfony\Component\Messenger\Middleware\SendMessageMiddleware;

// Setup dispatcher
$dispatcher = new EventDispatcher();

// Create transport
$transport = Transport::fromDsn('smtp://localhost', $dispatcher);

// Create handler
$handler = new MessageHandler($transport);

// Create message bus with handler
$bus = new MessageBus([
    new SendMessageMiddleware([]),
    new HandleMessageMiddleware(new HandlerResolver([
        SendEmailMessage::class => $handler,
    ])),
]);

// Create mailer with bus (enables async)
$mailer = new Mailer($transport, $bus, $dispatcher);

// Sending queues the email instead of blocking on SMTP
$mailer->send($email);
echo 'Email queued for sending';

// In worker process or testing:
// $handler($sendMessage); // Processes the queued message
```

--------------------------------

### Configure Mailer DSN Examples

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Common DSN configurations for various SMTP and local transport scenarios.

```php
// SMTP on localhost
'smtp://localhost'

// SMTP with authentication
'smtp://user:pass@smtp.example.com:587'

// SMTP with TLS (explicit)
'smtp://user:pass@smtp.example.com:587?encryption=tls'

// SMTP with SSL/TLS (implicit)
'smtps://user:pass@smtp.gmail.com:465'

// Sendmail with custom command
'sendmail:///usr/sbin/sendmail?command=/usr/sbin/sendmail%20-bs'

// SMTP with options
'smtp://user:pass@host?timeout=30&ping_threshold=100'
```

--------------------------------

### DSN parsing examples

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Demonstrates various DSN string formats including basic SMTP, authentication, query options, and URL-encoded credentials.

```php
use Symfony\Component\Mailer\Transport\Dsn;

// Basic SMTP
$dsn = Dsn::fromString('smtp://localhost');

// SMTP with authentication
$dsn = Dsn::fromString('smtp://user:pass@host:587');

// SMTP with options
$dsn = Dsn::fromString('smtp://user:pass@host:587?encryption=tls&timeout=30');

// API transport
$dsn = Dsn::fromString('sendgrid+api://api-key@default');

// URL-encoded credentials
$dsn = Dsn::fromString('smtp://user%40domain:pass%2Fword@host');
// After decoding: user='user@domain', password='pass/word'
```

--------------------------------

### SMTP Transport Examples

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Various SMTP configurations including localhost, authentication, and URL-encoded credentials.

```text
# Localhost without auth
smtp://localhost

# SMTP with STARTTLS authentication
smtp://user:pass@smtp.example.com:587?encryption=tls

# Gmail with SMTPS (implicit TLS)
smtps://user:pass@smtp.gmail.com:465

# URL-encoded credentials
smtp://user%40domain:pass%2Fword@host:587?encryption=tls
```

--------------------------------

### TagHeader Provider Usage

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/headers.md

Examples of using tags for provider-specific filtering and categorization.

```php
// Postmark uses tags for activity filtering
$email->getHeaders()->add(new TagHeader('password-reset'));

// Multiple tags for categorization
$email->getHeaders()->add(new TagHeader('transactional'));
$email->getHeaders()->add(new TagHeader('urgent'));
```

--------------------------------

### Implement event subscriber

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Example of using EventSubscriberInterface to handle mailer events within a class.

```php
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Mailer\Event\MessageEvent;
use Symfony\Component\Mailer\Event\SentMessageEvent;
use Symfony\Component\Mailer\Event\FailedMessageEvent;
use Symfony\Component\Messenger\Stamp\DelayStamp;
use Psr\Log\LoggerInterface;

class EmailEventListener implements EventSubscriberInterface
{
    public function __construct(private LoggerInterface $logger) {}

    public static function getSubscribedEvents(): array
    {
        return [
            MessageEvent::class => 'onMessage',
            SentMessageEvent::class => 'onSentMessage',
            FailedMessageEvent::class => 'onFailedMessage',
        ];
    }

    public function onMessage(MessageEvent $event): void
    {
        // Add tracking header
        $event->getMessage()->getHeaders()
            ->addTextHeader('X-Sent-At', date('Y-m-d H:i:s'));

        // Delay high-volume sends
        if ($event->isQueued() && $this->isHighVolume($event->getMessage())) {
            $event->addStamp(new DelayStamp(60000)); // 1 minute delay
        }
    }

    public function onSentMessage(SentMessageEvent $event): void
    {
        $this->logger->info('Email sent', [
            'message_id' => $event->getMessage()->getMessageId(),
        ]);
    }

    public function onFailedMessage(FailedMessageEvent $event): void
    {
        $this->logger->error('Email failed', [
            'error' => $event->getError()->getMessage(),
        ]);
    }

    private function isHighVolume($message): bool
    {
        // Custom logic
        return false;
    }
}
```

--------------------------------

### Display RoundRobinTransport String Representation

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/roundrobin-failover.md

Example of converting a RoundRobinTransport instance to a string.

```php
$transport = new RoundRobinTransport([
    Transport::fromDsn('smtp://host1'),
    Transport::fromDsn('smtp://host2'),
]);

echo $transport; // Output: roundrobin(smtp://host1 smtp://host2)
```

--------------------------------

### Rejecting Messages via Listener

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Example of rejecting a message based on sender blacklisting.

```php
public function onMessage(MessageEvent $event): void
{
    if ($this->isBlacklisted($event->getEnvelope()->getSender())) {
        $event->reject();
        $this->logger->info('Rejected email from ' . $event->getEnvelope()->getSender());
    }
}
```

--------------------------------

### Catching HttpTransportException

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/errors.md

Example of catching an HTTP transport exception and inspecting the response.

```php
use Symfony\Component\Mailer\Exception\HttpTransportException;

try {
    $transport->send($email);
} catch (HttpTransportException $e) {
    $response = $e->getResponse();
    echo 'HTTP Status: ' . $response->getStatusCode();
    echo 'Response Body: ' . $response->getContent();
}
```

--------------------------------

### Handle SentMessageEvent

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Example listener implementation to log the message ID and debug output after a successful send.

```php
public function onSentMessage(SentMessageEvent $event): void
{
    $messageId = $event->getMessage()->getMessageId();
    $this->logger->info('Email sent with ID: ' . $messageId);
    
    // Store debug output for troubleshooting
    $debug = $event->getMessage()->getDebug();
    if ($debug) {
        $this->logger->debug('SMTP Debug: ' . $debug);
    }
}
```

--------------------------------

### Consume Queued Emails

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/messenger.md

Use the console command to start a worker that processes queued email messages.

```bash
# Console command to process queued emails
bin/console messenger:consume async
```

--------------------------------

### Synchronous Email Sending Example

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/mailer.md

Basic usage of the Mailer class to send an email synchronously using an SMTP transport.

```php
use Symfony\Component\Mailer\Mailer;
use Symfony\
Component\Mailer\Transport;
use Symfony\Component\Mime\Email;

$transport = Transport::fromDsn('smtp://localhost');
$mailer = new Mailer($transport);

$email = (new Email())
    ->from('sender@example.com')
    ->to('recipient@example.com')
    ->subject('Hello')
    ->text('Test message');

$mailer->send($email);
```

--------------------------------

### Handle FailedMessageEvent

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Example listener implementation to log transport errors and trigger alerts upon message failure.

```php
public function onFailedMessage(FailedMessageEvent $event): void
{
    $error = $event->getError();
    
    if ($error instanceof TransportExceptionInterface) {
        $debug = $error->getDebug();
        $this->logger->error('Mail transport failed: ' . $debug);
    }
    
    $this->notificationService->alert(
        'Failed to send email: ' . $error->getMessage()
    );
}
```

--------------------------------

### Transport Creation Flow

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/architecture.md

Visual representation of the transport creation process starting from a DSN string.

```text
User provides DSN string
    │
    ├─> Transport.fromDsn()
    │
    ├─> Parse DSN syntax (failover/roundrobin)
    │
    ├─> For each DSN:
    │   │
    │   ├─> Try each factory.supports(dsn)
    │   │
    │   └─> factory.create(dsn)
    │       └─> Returns TransportInterface
    │
    └─> Build composite transport if needed
```

--------------------------------

### Get SMTP Envelope

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/messenger.md

Retrieves the SMTP envelope associated with the message.

```php
public function getEnvelope(): ?Envelope
```

--------------------------------

### Initialize MessageListener

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Demonstrates how to instantiate the MessageListener with custom headers and a Twig body renderer.

```php
use Symfony\Component\Mailer\EventListener\MessageListener;
use Symfony\
Component\Mime\Header\Headers;
use Symfony\Bridge\Twig\Mime\BodyRenderer;
use Twig\Environment;

// Headers to inject
$headers = new Headers();
$headers->addTextHeader('X-Mailer', 'Symfony Mailer');

// Template renderer for Twig
$twig = new Environment($fileSystemLoader);
$renderer = new BodyRenderer($twig);

// Create listener
$listener = new MessageListener($headers, $renderer);
```

--------------------------------

### Mailer::__construct

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Initializes a new Mailer instance.

```APIDOC
## Mailer::__construct(TransportInterface $transport, ?MessageBusInterface $bus, ?EventDispatcherInterface $dispatcher)

### Description
Initializes a new Mailer instance with the specified transport, optional message bus, and event dispatcher.

### Parameters
- **transport** (TransportInterface) - Required - Email transport.
- **bus** (MessageBusInterface) - Optional - Messenger bus for async sending.
- **dispatcher** (EventDispatcherInterface) - Optional - Event dispatcher for lifecycle events.
```

--------------------------------

### Get Original Message

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Retrieves the message in its original state before any transport-level modifications.

```php
public function getOriginalMessage(): RawMessage
```

--------------------------------

### Parsing DSN Strings with PHP

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Demonstrates how to use the Dsn::fromString method to parse a connection string and extract individual components.

```php
use Symfony\Component\Mailer\Transport\Dsn;

// Parse complex DSN
$dsn = Dsn::fromString(
    'smtps://user%40company.com:pass%2Fword@smtp.gmail.com:465?encryption=ssl&verify_peer=true'
);

// Extract components
echo $dsn->getScheme(); // Output: smtps
echo $dsn->getHost(); // Output: smtp.gmail.com
echo $dsn->getUser(); // Output: user@company.com
echo $dsn->getPassword(); // Output: pass/word
echo $dsn->getPort(); // Output: 465
echo $dsn->getOption('encryption'); // Output: ssl
echo $dsn->getBooleanOption('verify_peer'); // Output: 1 (true)
```

--------------------------------

### Get Processed Message

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Retrieves the final form of the message as sent by the transport.

```php
public function getMessage(): RawMessage
```

--------------------------------

### Get Recipient Addresses

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/envelope.md

Retrieves the current list of recipient addresses in addr-spec format.

```php
public function getRecipients(): Address[]
```

--------------------------------

### Get collected events

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Returns collected events, optionally filtered by transport name.

```php
public function getEvents(?string $name = null): MessageEvent[]
```

--------------------------------

### Construct a Dsn object

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Initializes a new Dsn instance with scheme, host, and optional credentials or configuration parameters.

```php
public function __construct(
    string $scheme,
    string $host,
    ?string $user = null,
    ?string $password = null,
    ?int $port = null,
    array $options = []
)
```

--------------------------------

### Get Message as Iterable

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Returns the message content as an iterable of chunks for memory-efficient streaming.

```php
public function toIterable(): iterable
```

--------------------------------

### Sending emails with Envelope configurations in PHP

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/envelope.md

Demonstrates automatic envelope creation, manual envelope overrides, and the use of delayed envelopes for dynamic header extraction.

```php
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Envelope;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mime\Email;
use Symfony\Component\Mime\Address;

$transport = Transport::fromDsn('smtp://localhost');
$mailer = new Mailer($transport);

// Create email
$email = (new Email())
    ->from('noreply@example.com')
    ->to('user@example.com')
    ->subject('Confirmation');

// Option 1: Let envelope be created automatically from headers
$mailer->send($email);

// Option 2: Override envelope with explicit sender/recipients
$envelope = new Envelope(
    new Address('bounce@example.com'), // Different from From header
    [new Address('user@example.com')]
);
$mailer->send($email, $envelope);

// Option 3: Use delayed envelope for dynamic extraction
$envelope = Envelope::create($email);
// Envelope extracts from headers when first accessed
```

--------------------------------

### Configure Mailer with Multiple Transports

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transports.md

Use Transport::fromDsns to initialize multiple transports and inject them into a Mailer instance for routing.

```php
use SymfonyemponentmailerMailer;
use SymfonyemponentmailerTransport;
use SymfonyemponentMimeEmail;

// Create multiple transports
$transports = Transport::fromDsns([
    'smtp' => 'smtp://localhost',
    'sendgrid' => 'sendgrid+api://key@default',
    'mailgun' => 'mailgun+api://domain%40...',
]);

$mailer = new Mailer($transports);

// Route transactional email through SMTP
$transactional = (new Email())
    ->from('noreply@example.com')
    ->to('user@example.com')
    ->subject('Verification Code')
    ->text('Your code: 123456');
$transactional->getHeaders()->addTextHeader('X-Transport', 'smtp');

// Route marketing email through Sendgrid (has templates, analytics)
$marketing = (new Email())
    ->from('marketing@example.com')
    ->to('subscriber@example.com')
    ->subject('New Product Launch');
$marketing->getHeaders()->addTextHeader('X-Transport', 'sendgrid');

// Send both through the same Mailer instance
$mailer->send($transactional);
$mailer->send($marketing);
```

--------------------------------

### Initialize SmtpTransport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/smtp-transport.md

Demonstrates creating a new SmtpTransport instance using default settings or custom stream, dispatcher, and logger dependencies.

```php
use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
use Symfony\Component\Mailer\Transport\Smtp\Stream\SocketStream;

// Default socket-based transport
$transport = new SmtpTransport();

// With event dispatcher and logger
$transport = new SmtpTransport($stream, $dispatcher, $logger);
```

--------------------------------

### Dsn::__construct

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Creates a new Dsn instance with the specified connection components.

```APIDOC
## __construct

### Description
Initializes a new Dsn object with the provided connection details.

### Signature
`public function __construct(string $scheme, string $host, ?string $user = null, ?string $password = null, ?int $port = null, array $options = [])`

### Parameters
- **$scheme** (string) - Required - DSN scheme (e.g., smtp, sendgrid+api)
- **$host** (string) - Required - Host or service name (e.g., localhost, default)
- **$user** (string|null) - Optional - Username from DSN (URL-decoded)
- **$password** (string|null) - Optional - Password from DSN (URL-decoded, marked sensitive)
- **$port** (int|null) - Optional - Port number
- **$options** (array) - Optional - Query parameters as key-value pairs
```

--------------------------------

### Get messages from events

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Returns messages from collected events, optionally filtered by transport name.

```php
public function getMessages(?string $name = null): RawMessage[]
```

--------------------------------

### Constructing a Transport Factory

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Initializes the transport factory with a collection of transport factories.

```php
public function __construct(iterable $factories)
```

--------------------------------

### Get unique transport names

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Returns a list of unique transport names from collected events.

```php
public function getTransports(): string[]
```

--------------------------------

### Get Debug Information

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Retrieves accumulated diagnostic data such as SMTP logs or API responses.

```php
public function getDebug(): string
```

--------------------------------

### Load Transport from Environment Variable

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Initialize a transport instance using the DSN defined in the environment.

```php
$transport = Transport::fromDsn($_ENV['MAILER_DSN']);
```

--------------------------------

### Get Envelope

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Retrieves the SMTP envelope containing sender and recipient information used for delivery.

```php
public function getEnvelope(): Envelope
```

--------------------------------

### Display File Structure

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/README.md

Visual representation of the documentation directory layout.

```text
/api-reference/
  ├─ mailer.md              # Mailer class
  ├─ transport.md           # Transport factory
  ├─ envelope.md            # Envelope class
  ├─ sent-message.md        # SentMessage class
  ├─ smtp-transport.md      # SMTP transport
  ├─ sendmail-transport.md  # Sendmail transport
  ├─ null-transport.md      # Null transport
  ├─ roundrobin-failover.md # Load balancing & failover
  ├─ transports.md          # Named transport routing
  ├─ dsn.md                 # DSN parsing
  ├─ events.md              # Event classes
  ├─ messenger.md           # Async sending
  ├─ message-listener.md    # Event listener
  └─ headers.md             # Custom headers

/
  ├─ architecture.md        # High-level design
  ├─ configuration.md       # Configuration reference
  ├─ errors.md              # Exception reference
  ├─ quick-start.md         # Common patterns
  ├─ types.md               # Type definitions
  └─ README.md              # This file
```

--------------------------------

### Configure Logging

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Sets the logging channel and level via environment variables.

```bash
# .env
LOG_CHANNEL=mailer
LOG_LEVEL=debug
```

--------------------------------

### getHost()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Returns the host component from the DSN.

```APIDOC
## getHost()

### Description
Returns the host name or service identifier.

### Signature
`public function getHost(): string`

### Returns
- **string** - Host name or service identifier.
```

--------------------------------

### Configure Transport via DSN

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/quick-start.md

Initialize a mailer transport using a DSN string, defaulting to a null transport if the environment variable is missing.

```php
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mailer\Mailer;

// Load from environment (empty = no sending)
$dsn = $_ENV['MAILER_DSN'] ?? 'null://';

$transport = Transport::fromDsn($dsn);
$mailer = new Mailer($transport);

$mailer->send($email);
```

--------------------------------

### Initialize Transports

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transports.md

Create a Transports instance by passing an array of named transports created via Transport::fromDsn.

```php
use SymfonyemponentmailerTransport;
use SymfonyemponentmailerTransportTransports;

$transports = new Transports([
    'primary' => Transport::fromDsn('smtp://smtp1.example.com'),
    'backup' => Transport::fromDsn('smtp://smtp2.example.com'),
    'api' => Transport::fromDsn('sendgrid+api://...'),
]);
```

--------------------------------

### Adding a Delay Stamp to a Queued Message

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Example of adding a DelayStamp to a queued message to schedule delivery.

```php
use Symfony\Component\Messenger\Stamp\DelayStamp;

public function onMessage(MessageEvent $event): void
{
    if ($event->isQueued()) {
        // Delay sending by 5 minutes
        $event->addStamp(new DelayStamp(5 * 60 * 1000));
    }
}
```

--------------------------------

### Adding Metadata Headers to Email

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/headers.md

Demonstrates how to attach custom metadata key-value pairs to an email.

```php
use Symfony\
Component\Mailer\Header\MetadataHeader;
use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('sender@example.com')
    ->to('user@example.com')
    ->subject('Order Confirmation');

// Add metadata
$email->getHeaders()->add(new MetadataHeader('order_id', '12345'));
$email->getHeaders()->add(new MetadataHeader('customer_id', 'cust_789'));
$email->getHeaders()->add(new MetadataHeader('store_name', 'Main Store'));
```

--------------------------------

### Apply HEADER_ADD rule

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Demonstrates usage of the HEADER_ADD rule to allow multiple X-Tag headers.

```php
$headers = new Headers();
$headers->addTextHeader('X-Tag', 'important');

$listener = new MessageListener($headers);
$listener->addHeaderRule('x-tag', MessageListener::HEADER_ADD);

// If message already has X-Tag, another is added
// Allows multiple X-Tag values
```

--------------------------------

### Get Transport Message ID

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sent-message.md

Retrieves the transport-specific tracking ID, distinct from the RFC Message-ID header.

```php
public function getMessageId(): string
```

--------------------------------

### Recommended Batch Mode Command

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sendmail-transport.md

The recommended command string for batch mode, including flags to prevent premature termination.

```text
/usr/sbin/sendmail -oi -t
```

--------------------------------

### Configure API Transport DSN

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Example of an API-based transport configuration using a provider key and region parameter.

```text
sendgrid+api://key@default?region=us
```

--------------------------------

### Adding Tag Headers to Email

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/headers.md

Demonstrates how to add single or multiple tag headers to an email instance.

```php
use Symfony\Component\Mailer\Header\TagHeader;
use Symfony\
Component\Mime\Email;

$email = (new Email())
    ->from('sender@example.com')
    ->to('recipient@example.com')
    ->subject('Welcome');

// Add tag header
$email->getHeaders()->add(new TagHeader('welcome'));

// Or multiple tags
$email->getHeaders()->add(new TagHeader('important'));
$email->getHeaders()->add(new TagHeader('onboarding'));
```

--------------------------------

### Initialize MessageHandler

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/messenger.md

Creates a new MessageHandler instance using a specific transport.

```php
use Symfony\Component\Mailer\Messenger\MessageHandler;
use Symfony\Component\Mailer\Transport;

$transport = Transport::fromDsn('smtp://localhost');
$handler = new MessageHandler($transport);
```

--------------------------------

### Get string representation of SMTP transport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/smtp-transport.md

Retrieves the connection string for the transport, typically used for debugging or logging.

```php
$transport = new SmtpTransport();
$stream = $transport->getStream();
if ($stream instanceof SocketStream) {
    echo $transport; // Output: smtp://localhost or smtps://host:465
}
```

--------------------------------

### Apply HEADER_REPLACE rule

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Demonstrates usage of the HEADER_REPLACE rule to overwrite existing custom headers.

```php
$headers = new Headers();
$headers->addTextHeader('X-Custom', 'injected-value');

$listener = new MessageListener($headers);
$listener->addHeaderRule('x-custom', MessageListener::HEADER_REPLACE);

// Any existing X-Custom header is removed
// Injected value replaces it
```

--------------------------------

### getOption()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Returns a query option value.

```APIDOC
## getOption()

### Description
Returns a query option value with an optional default.

### Parameters
- **$key** (string) - Required - Option key (case-sensitive).
- **$default** (mixed) - Optional - Default if key not present.

### Returns
- **mixed** - Option value or default.
```

--------------------------------

### Apply HEADER_SET_IF_EMPTY rule

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Demonstrates usage of the HEADER_SET_IF_EMPTY rule to conditionally add a From header.

```php
$headers = new Headers();
$headers->addTextHeader('From', 'noreply@example.com');

$listener = new MessageListener($headers);
$listener->addHeaderRule('from', MessageListener::HEADER_SET_IF_EMPTY);

// If message already has a From header, injected one is ignored
// If message has no From header, injected one is added
```

--------------------------------

### Get Sender Address

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/envelope.md

Retrieves the sender address. Use getAddress() to extract the raw addr-spec format for SMTP commands.

```php
public function getSender(): Address
```

```php
$address = $envelope->getSender()->getAddress(); // Returns just "user@domain.com"
```

--------------------------------

### SendmailTransport::__construct

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sendmail-transport.md

Initializes the SendmailTransport with a specific binary path and optional dependencies.

```APIDOC
## __construct

### Description
Initializes a new instance of the SendmailTransport class.

### Parameters
- **$command** (string|null) - Optional - Sendmail binary path and flags (default: /usr/sbin/sendmail -bs)
- **$dispatcher** (EventDispatcherInterface|null) - Optional - Event dispatcher
- **$logger** (LoggerInterface|null) - Optional - PSR-3 logger

### Usage Example
```php
$transport = new SendmailTransport('/usr/sbin/sendmail -bs');
```
```

--------------------------------

### Create a single transport with fromDsn()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Defines the method signature for creating a transport instance from a DSN string.

```php
public static function fromDsn(
    string $dsn,
    ?EventDispatcherInterface $dispatcher = null,
    ?HttpClientInterface $client = null,
    ?LoggerInterface $logger = null
): TransportInterface
```

--------------------------------

### MessageListener Header Rule Constants

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Lists the available constants for defining header injection behavior and the default rules applied.

```php
const HEADER_SET_IF_EMPTY = 1;  // Only set if header doesn't exist
const HEADER_ADD = 2;            // Always add header (allows duplicates)
const HEADER_REPLACE = 3;        // Replace existing header
const DEFAULT_RULES = [
    'from' => self::HEADER_SET_IF_EMPTY,
    'return-path' => self::HEADER_SET_IF_EMPTY,
    'reply-to' => self::HEADER_ADD,
    'to' => self::HEADER_SET_IF_EMPTY,
    'cc' => self::HEADER_ADD,
    'bcc' => self::HEADER_ADD,
];
```

--------------------------------

### Create Transport from DSN String

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Manually instantiate a transport using a DSN string.

```php
use Symfony\Component\Mailer\Transport;

$dsn = 'smtp://localhost:25';
$transport = Transport::fromDsn($dsn);
```

--------------------------------

### Instantiating FailoverTransport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/roundrobin-failover.md

Create a failover transport by passing an array of DSN-configured transports to the constructor.

```php
use Symfony\Component\Mailer\Transport\FailoverTransport;
use Symfony\
Component\Mailer\Transport;

$transport = new FailoverTransport([
    Transport::fromDsn('smtp://primary.example.com'),
    Transport::fromDsn('smtp://secondary.example.com'),
    Transport::fromDsn('smtp://tertiary.example.com'),
]);
```

--------------------------------

### Queue and Dispatch Email

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/messenger.md

Wraps an email in a SendEmailMessage and dispatches it to the message bus.

```php
use Symfony\Component\Mailer\Messenger\SendEmailMessage;
use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('sender@example.com')
    ->to('recipient@example.com')
    ->subject('Test');

// Create message for queueing
$sendMessage = new SendEmailMessage($email);

// Dispatch to message bus
$bus->dispatch($sendMessage);
```

--------------------------------

### Create a Custom Body Renderer

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/architecture.md

Implement the BodyRendererInterface to define custom message body rendering logic.

```php
class MyRenderer implements BodyRendererInterface {
    public function render(BodyRendererInterface $message): void {
        // Render message body
    }
}
```

--------------------------------

### Subscribe to mailer events

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Demonstrates using EventDispatcher to listen for MessageEvent, SentMessageEvent, and FailedMessageEvent.

```php
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\Mailer\Event\MessageEvent;
use Symfony\Component\Mailer\Event\SentMessageEvent;
use Symfony\Component\Mailer\Event\FailedMessageEvent;
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport;

$dispatcher = new EventDispatcher();

// Inspect and modify before sending
$dispatcher->addListener(MessageEvent::class, function(MessageEvent $event) {
    $envelope = $event->getEnvelope();
    echo 'Sending to: ' . implode(', ', 
        array_map(fn($a) => $a->getAddress(), $envelope->getRecipients())
    );
});

// Log successful sends
$dispatcher->addListener(SentMessageEvent::class, function(SentMessageEvent $event) {
    $messageId = $event->getMessage()->getMessageId();
    error_log("Email sent: $messageId");
});

// Handle failures
$dispatcher->addListener(FailedMessageEvent::class, function(FailedMessageEvent $event) {
    error_log('Email failed: ' . $event->getError()->getMessage());
});

$transport = Transport::fromDsn('smtp://localhost', $dispatcher);
$mailer = new Mailer($transport, null, $dispatcher);
```

--------------------------------

### MessageListener Constructor Signature

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Defines the constructor parameters for initializing the MessageListener.

```php
public function __construct(
    ?Headers $headers = null,
    ?BodyRendererInterface $renderer = null,
    array $headerRules = self::DEFAULT_RULES
)
```

--------------------------------

### Asynchronous Email Sending with Messenger

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/mailer.md

Configuring the Mailer with a message bus and event dispatcher to enable asynchronous email queuing.

```php
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Messenger\MessageBus;
use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware;
use Symfony\Component\Messenger\Middleware\SendMessageMiddleware;
use Symfony\Component\Messenger\Handler\HandlerResolver;

$dispatcher = new EventDispatcher();
$transport = Transport::fromDsn('smtp://localhost', $dispatcher);

// Create a message bus with handlers
$bus = new MessageBus([
    new SendMessageMiddleware([]),
    new HandleMessageMiddleware(new HandlerResolver([
        // Handler mapping configured here
    ])),
]);

$mailer = new Mailer($transport, $bus, $dispatcher);

// This will queue the message instead of sending immediately
$mailer->send($email);
```

--------------------------------

### Initialize ESMTP transport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/smtp-transport.md

Initializes an ESMTP transport instance to enable authentication support.

```php
use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;

$transport = new EsmtpTransport($stream);
// ESMTP provides AUTH support (PLAIN, LOGIN, CRAM-MD5, XOAUTH2)
```

--------------------------------

### Initialize NullTransport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/null-transport.md

Instantiate the NullTransport and inject it into the Mailer to silently discard all outgoing emails.

```php
use Symfony\Component\Mailer\Transport\NullTransport;
use Symfony\Component\Mailer\Mailer;

$transport = new NullTransport();
$mailer = new Mailer($transport);

// All emails are silently discarded
$mailer->send($email);
```

--------------------------------

### Constructing an Envelope

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/envelope.md

Instantiate an Envelope by providing a sender Address and an array of recipient Address objects.

```php
public function __construct(
    Address $sender,
    Address[] $recipients
)
```

```php
use Symfony	Component	Mailer	Envelope;
use Symfony	Component	Mime	Address;

$envelope = new Envelope(
    new Address('sender@example.com'),
    [
        new Address('recipient1@example.com'),
        new Address('recipient2@example.com'),
    ]
);
```

--------------------------------

### setPingThreshold()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/smtp-transport.md

Sets the minimum idle time before pinging the server with NOOP.

```APIDOC
## setPingThreshold()

### Description
Sets the minimum idle time before sending a NOOP command to keep the connection alive.

### Signature
`public function setPingThreshold(int $seconds): static`

### Parameters
- **$seconds** (int) - Required - Seconds idle before NOOP ping

### Returns
- **static** - The transport instance for method chaining
```

--------------------------------

### Create multiple transports with fromDsns()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/transport.md

Defines the method signature for creating a collection of named transports from an array of DSN strings.

```php
public static function fromDsns(
    array $dsns,
    ?EventDispatcherInterface $dispatcher = null,
    ?HttpClientInterface $client = null,
    ?LoggerInterface $logger = null
): Transports
```

--------------------------------

### Configure Default Headers

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Sets default headers for outgoing messages using the MessageListener.

```php
use Symfony\Component\Mailer\EventListener\MessageListener;
use Symfony\Component\Mime\Header\Headers;

$headers = new Headers();
$headers->addTextHeader('X-Mailer', 'MyApp/1.0');
$headers->addTextHeader('X-Priority', '3');

$listener = new MessageListener($headers);
```

--------------------------------

### MessageEvent Constructor

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/events.md

Initializes a new MessageEvent instance.

```php
public function __construct(
    RawMessage $message,
    Envelope $envelope,
    string $transport,
    bool $queued = false
)
```

--------------------------------

### getScheme()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/dsn.md

Returns the DSN scheme component.

```APIDOC
## getScheme()

### Description
Returns the DSN scheme (e.g., smtp, smtps, sendgrid+api).

### Signature
`public function getScheme(): string`

### Returns
- **string** - The scheme component.
```

--------------------------------

### Configure round-robin load balancing

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/quick-start.md

Distribute outgoing emails across multiple SMTP servers using the roundrobin DSN wrapper.

```php
use Symfony	symfony	Component	Mailer	Transport;

// Round-robin load balancing
$transport = Transport::fromDsn(
    'roundrobin(smtp://host1 smtp://host2 smtp://host3)'
);

$mailer = new Mailer($transport);
```

--------------------------------

### Configure SMTP Transport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/quick-start.md

Sets up an SMTP transport with custom stream settings, restart thresholds, and ping intervals.

```php
use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
use Symfony\Component\Mailer\Transport\Smtp\Stream\SocketStream;

$stream = new SocketStream();
$stream->setHost('smtp.example.com');
$stream->setPort(587);
$stream->setTLS(true);

$transport = new SmtpTransport($stream);

// Restart connection every 50 messages
$transport->setRestartThreshold(50, 1);

// Ping server if idle >60 seconds
$transport->setPingThreshold(60);

// Set HELO domain
$transport->setLocalDomain('mail.example.com');
```

--------------------------------

### __toString()

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/smtp-transport.md

Returns a string representation of the transport instance.

```APIDOC
## __toString()

### Description
Returns a string representation of the transport.

### Returns
- **string** - Format: smtp[s]://host[:port] or smtp://sendmail

### Example
```php
$transport = new SmtpTransport();
$stream = $transport->getStream();
if ($stream instanceof SocketStream) {
    echo $transport; // Output: smtp://localhost or smtps://host:465
}
```
```

--------------------------------

### Interactive Mode Command

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/sendmail-transport.md

The recommended command string for interactive SMTP-like mode.

```text
/usr/sbin/sendmail -bs
```

--------------------------------

### Create a Custom Event Listener

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/architecture.md

Implement the EventSubscriberInterface to hook into mailer events.

```php
class MyListener implements EventSubscriberInterface {
    public static function getSubscribedEvents(): array {
        return [MessageEvent::class => 'onMessage'];
    }
    public function onMessage(MessageEvent $event): void {
        // Custom logic
    }
}
```

--------------------------------

### Catching Specific Mailer Exceptions

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/errors.md

Demonstrates how to handle different types of mailer exceptions individually, such as HTTP transport failures, general transport issues, and configuration errors.

```php
use Symfony\Component\Mailer\Exception\HttpTransportException;
use Symfony\Component\Mailer\Exception\TransportExceptionInterface;
use Symfony\Component\Mailer\Exception\InvalidArgumentException;

try {
    $mailer->send($email);
} catch (HttpTransportException $e) {
    // API transport failed
    $response = $e->getResponse();
    echo 'HTTP ' . $response->getStatusCode();
} catch (TransportExceptionInterface $e) {
    // SMTP or other transport error
    echo 'Transport error: ' . $e->getDebug();
} catch (InvalidArgumentException $e) {
    // Configuration error
    echo 'Invalid configuration: ' . $e->getMessage();
}
```

--------------------------------

### Create a Custom Transport

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/architecture.md

Implement the TransportInterface to define custom email sending logic.

```php
class MyTransport implements TransportInterface {
    public function send(RawMessage $message, ?Envelope $envelope = null): ?SentMessage {
        // Custom sending logic
    }
}
```

--------------------------------

### Send a Basic Email with Symfony Mailer

Source: https://github.com/symfony/mailer/blob/8.2/README.md

Demonstrates how to send a simple text or HTML email using the Mailer component. Ensure you have a transport configured, like SMTP.

```php
use Symfony\Component\Mailer\Transport;
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mime\Email;

$transport = Transport::fromDsn('smtp://localhost');
$mailer = new Mailer($transport);

$email = (new Email())
    ->from('hello@example.com')
    ->to('you@example.com')
    //->cc('cc@example.com')
    //->bcc('bcc@example.com')
    //->replyTo('fabien@example.com')
    //->priority(Email::PRIORITY_HIGH)
    ->subject('Time for Symfony Mailer!')
    ->text('Sending emails is fun again!')
    ->html('<p>See Twig integration for better HTML integration!</p>');

$mailer->send($email);
```

--------------------------------

### Create NullTransport via DSN

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/null-transport.md

Use the Transport factory to instantiate a NullTransport instance using the null:// DSN.

```php
use Symfony\Component\Mailer\Transport;

$transport = Transport::fromDsn('null://');
```

--------------------------------

### NullTransport::__construct

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/null-transport.md

Initializes a new instance of the NullTransport class.

```APIDOC
## __construct

### Description
Initializes the NullTransport with an optional event dispatcher and logger.

### Parameters
- **$dispatcher** (EventDispatcherInterface|null) - Optional - Event dispatcher
- **$logger** (LoggerInterface|null) - Optional - PSR-3 logger
```

--------------------------------

### Address Constructor

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/types.md

Constructor for the Address class, representing an email address with an optional display name.

```php
public function __construct(string $address, string $name = '')
```

--------------------------------

### Visualize Message Queue Flow

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/architecture.md

Diagram illustrating the lifecycle of an email from dispatch to worker processing.

```text
Mailer.send(email)
    │
    ├─ Create SendEmailMessage(email, envelope)
    │
    ├─ Bus.dispatch(SendEmailMessage)
    │
    └─> Stored in Messenger transport (DB, Redis, RabbitMQ, etc.)

    =========== Worker ===========

    Worker reads from transport
        │
        ├─ Load SendEmailMessage
        │
        ├─ Route to MessageHandler
        │
        └─> MessageHandler calls Transport.send()
```

--------------------------------

### Register MessageListener with EventDispatcher

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/api-reference/message-listener.md

Configure the EventDispatcher and attach the MessageListener to the Mailer transport.

```php
use Symfony
ent
use Symfony
ent
use Symfony
ent
use Symfony
ent;

$dispatcher = new EventDispatcher();

// Create listener with headers and renderer
$headers = new Headers();
$headers->addTextHeader('X-Mailer', 'Symfony');

$listener = new MessageListener($headers, $renderer);

// Register listener
$dispatcher->addSubscriber($listener);

// Create transport and mailer with dispatcher
$transport = Transport::fromDsn('smtp://localhost', $dispatcher);
$mailer = new Mailer($transport, null, $dispatcher);

// When sending emails, listener automatically manipulates headers and renders templates
$mailer->send($email);
```

--------------------------------

### Native Transport Configuration

Source: https://github.com/symfony/mailer/blob/8.2/_autodocs/configuration.md

Uses PHP's native mail() function.

```text
native://
```
Tokens:
Raw