Advanced — Mailer

Spiral provides a simple email API powered by the symfony/mailer component.

Note
The component is available by default in the application bundle.

Emails are delivered via a "transport". Out of the box, you can deliver emails over SMTP by configuring the DSN in your .env file (the user, pass and port parameters are optional).

#Installation

To enable the component, you need to add the Spiral\SendIt\Bootloader\MailerBootloader class to the bootloaders list.

public function defineBootloaders(): array
{
    return [
        // ...
        \Spiral\SendIt\Bootloader\MailerBootloader::class,
        // ...
    ];
}

protected const LOAD = [
    // ...
    \Spiral\SendIt\Bootloader\MailerBootloader::class,
    // ...
];

This bootloader configures the base bindings, default settings, and a queue for sending emails. It will also automatically register the Spiral\SendIt\Bootloader\BuilderBootloader, which registers the spiral/views component and provides the ability to create email templates using the Stempler template engine.

#Configuration

MAILER_DSN=smtp://username:password@example.com:25
MAILER_FROM=John Smith

MAILER_QUEUE_CONNECTION=roadrunner
MAILER_QUEUE=emails

return [
    /**
     * -------------------------------------------------------------------------
     *  Transport setup
     * -------------------------------------------------------------------------
     *
     * The MAILER_DSN isn't a real address: it's a convenient format that offloads most of the configuration work to mailer.
     * Supported formats are compatible with the symfony/mailer component.
     */
    'dsn' => env('MAILER_DSN'),

    /**
     * -------------------------------------------------------------------------
     *  From
     * -------------------------------------------------------------------------
     *
     * Instead of calling ->from() on each Email you create, you can configure this value globally.
     */
    'from' => env('MAILER_FROM'),

    /**
     * -------------------------------------------------------------------------
     *  Configuration queue connection
     * -------------------------------------------------------------------------
     *
     * This section allows you to configure the `queue` and the `driver` for sending emails.
     * The `queueConnection` with the value `sync` allows you to send emails without using a queue.
     */
    'queue' => env('MAILER_QUEUE'), // won't be used for sync queue
    'queueConnection' => env('MAILER_QUEUE_CONNECTION', 'sync'),
];

#DSN

The MAILER_DSN parameter is used to configure the transport for delivering emails. The component uses the symfony/mailer component to send emails, and it supports several built-in transports, including SMTP, sendmail, and the PHP mail() function.

Note
The DSN (Data Source Name) is a string that specifies the transport to be used, and can include options such as the user, password, and port. Here is an example: smtp://username:password@example.com:25

Note
You can find more information about the different types of transports supported by the symfony/mailer component, and how to configure them, in the official Symfony documentation

#Custom mailer transport

In addition to the built-in transports supported by the symfony/mailer component, Spiral also allows you to use custom transports.

To use a custom transport, you will need to create a class that implements the Symfony\Component\Mailer\Transport\TransportInterface which is a part of symfony/mailer component. This class should handle the logic of sending an email using the desired transport.

Let's imagine that you have multiple DSN transports, and you want to use the Round Robin algorithm to select one of them for sending emails.

Here is an example of how to use custom transport:

use Spiral\Boot\Bootloader\Bootloader;
use Symfony\Component\Mailer\Transport\TransportInterface;
use Symfony\Component\Mailer\Transport\RoundRobinTransport;
use Symfony\Component\Mailer\Transport;

class AppBootloader extends Bootloader
{
    protected const DEPENDENCIES = [
        \Spiral\SendIt\Bootloader\MailerBootloader::class,
    ];
    
    protected const SINGLETONS = [
        TransportInterface::class => [self::class, 'initTransport'],
    ];
    
    public function initTransport(): TransportInterface
    {
        $transports = [];
        
        $dsns = [
            'smtp://...',
            'smtp://...',
            // ...
        ];

        foreach($dsns as $dsn) {
            $transports[] = Transport::fromDsn($dsn);
        }

        return new RoundRobinTransport($transports);
    }
}

Note
It's important to note that creating and configuring custom transports can be complex and may require deep understanding of Symfony Mailer component and its Transport interface

#Queue

Sending emails can be a time-consuming task, and if your application sends a large number of emails, it can slow down the overall performance of your application. One way to mitigate this issue is to use queue jobs to send emails.

Spiral provides an easy way to set up a queue connection and pipeline for sending emails.

In the .env file, you can configure the queue connection and pipeline to use for sending emails by setting the MAILER_QUEUE_CONNECTION and MAILER_QUEUE variables.

You can also configure the email queue in the app/config/mailer.php configuration file.

See more
Read more about queue connection configuration in the Queue — Installation and Configuration section.

#Usage

The component provides an ability to compose content-rich email templates using Stempler views:

<extends:sendit:builder subject="I'm afraid I can't do that"/>
<use:bundle path="sendit:bundle"/>

<email:attach path="{{ $attachment }}" name="attachment.txt"/>

<block:html>
    <p>I'm sorry, {{ $name }}!</p>
    <p>
        <email:image path="path/to/image.png"/>
    </p>
</block:html>

To use:

use Spiral\Mailer\MailerInterface;
use Spiral\Mailer\Message;

public function send(MailerInterface $mailer): void
{
    $mailer->send(new Message(
        'template.dark.php', 
        'email@domain.com',
        [
            'name' => 'Dave',
            'attachment' => __FILE__,
        ]
    ));
}

#Sending messages with a delay

The component allows sending messages with a delay. The delay time is set using the setDelay method:

use Spiral\Mailer\Message;

$message = new Message('test', 'email@domain.com');
$message->setDelay(new \DateTimeImmutable('+ 60 minute'));
// or
$message->setDelay(new \DateInterval('PT60S'));
// or
$message->setDelay(100);

#Custom mail transport

In some cases, you may need to use custom mail that are not provided by the symfony/mailer component, In this case, you can register a custom transport by using the Spiral\SendIt\TransportRegistryInterface interface.

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\SendIt\TransportRegistryInterface;
use Symfony\Component\Mailer\Transport\c;

class AppBootloader extends Bootloader 
{
    public function boot(TransportRegistryInterface $registry): void
    {
        $registry->registerTransport(new SendmailTransportFactory(...));
    }
}

#Events

Note
To learn more about dispatching events, see the Events section in our documentation.