Transports
The null transport is the default, which means a fresh installation silently drops mail until SMTP is configured. That’s deliberate: it keeps a half-configured installation from emailing real users.
See Mailer settings and SMTP for the administrator side.
Sending
send(TransactionalEmailInterface $email, string|array $to, array $data = [], array $attachments = []) sends a registered email. It does nothing while an administrator has the email turned off, and otherwise renders the email’s template with your data. The locale key picks the recipient’s language. Attachments are Shared\Infrastructure\Email\Attachment objects:
sendTemplate(string|array $to, ?string $template = null, ?array $data = null, ?array $attachments = null) is the lower-level call underneath. It renders and sends any template, with no on/off switch. Use send() for anything an administrator should be able to turn off.
Both merge every option into the template data, so templates can read option.site.name, brand settings and policy links without the caller passing them. Both also catch transport errors and log them as “Failed to send email”, so a mail failure never breaks the caller, and the caller can’t tell it failed.
The sender comes from option.mail.from.address and option.mail.from.name.
Templates
Templates live inresources/emails and are registered as the @emails Twig namespace. Each one extends layout.twig and defines a subject block and a content block.
A translated copy of an
@emails template can sit in resources/emails/{locale}. When the data passed to the email has a matching locale, that directory is searched first. See Email templates for more details.
Transactional emails
Every email the application sends on its own is registered with the service collection underShared\Infrastructure\Email\TransactionalEmailInterface. Registered emails are listed under Settings → Email → Emails, grouped by category, each with a Preview button and, unless it’s always on, an on/off switch.
Shared\Infrastructure\Email\AbstractTransactionalEmail supplies the defaults most emails want: on by default, can be turned off, no legacy option. Extend it and implement the rest.
EmailCategory defines the built-in groups, shown in this order: ACCOUNT (account), WORKSPACE (workspace), BILLING (billing) and ADMIN (admin). Any other category string is listed after them, with a label made from the string.
Switches are saved in the emails option, as emails.<key>.enabled. Shared\Infrastructure\Email\EmailSettings reads them:
EmailSettings reads the database each time rather than the cached options, so a long-running queue worker stops sending an email as soon as it’s turned off.
Core emails
What triggers mail
Whether the welcome email waits for verification depends on the verification policy. The billing emails run in the background because attaching an invoice means fetching its PDF from the invoicing service. See Billing for when each is sent.
Mail sent from a listener or request handler is sent inside that request, so a slow or unreachable SMTP server slows the request down. Keep timeouts short, and prefer a nearby relay.
Sending from a plugin
Register your email so administrators can preview it and turn it off. Start with the class:src/DigestEmail.php
boot():
src/Plugin.php
templates/emails/digest.twig
Testing
- Point SMTP at a local catcher, such as Mailpit or MailHog, while developing.
- With the null transport, messages are logged rather than sent: check
var/log/app-*.log. - Verify the “from” address is one your provider allows, or messages will be rejected or filtered.