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).
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,
// ...
];
}
Read more about bootloaders in the Framework — Bootloaders section.
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.
You can configure the component via .env
variables:
MAILER_DSN=smtp://username:password@example.com:25
MAILER_FROM=John Smith
MAILER_QUEUE_CONNECTION=roadrunner
MAILER_QUEUE=emails
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
DSN protocol | Example | Description |
---|---|---|
smtp | smtp://user:pass@smtp.example.com:25 |
Mailer uses an SMTP server to send emails |
sendmail | sendmail://default |
Mailer uses the local sendmail binary to send emails |
native | native://default |
Mailer uses the sendmail binary and options configured in the sendmail_path setting of php.ini. On Windows hosts, Mailer fallbacks to smtpand smtp_port php.inisettings when sendmail_path` is not configured. |
Note
You can find more information about the different types of transports supported by thesymfony/mailer
component, and how to configure them, in the official Symfony documentation
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
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.
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__,
]
));
}
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);
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(...));
}
}
Event | Description |
---|---|
Spiral\SendIt\Event\MessageSent | The Event will be fired after sending the message. |
Spiral\SendIt\Event\MessageNotSent | The Event is fired if the message could not be sent. |
Note
To learn more about dispatching events, see the Events section in our documentation.