Skip to main content
Email is sent through Symfony Mailer, with templates rendered by Twig. Which transport is used depends on what an administrator configured.

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 in resources/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 under Shared\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
Register it in your plugin’s boot():
src/Plugin.php
Write the template against the shared layout, so your message matches the rest of the installation’s mail:
templates/emails/digest.twig
Then send it, from a job rather than a request when you send more than one:
Keep the preview data shaped like what you send, so the preview shows what recipients get. A template that fails with the sample data reports its error in the preview instead of failing the page.
Don’t send bulk mail through this path. It’s for transactional messages, sent one at a time. Marketing sends belong in a dedicated platform; see Event-driven integrations.

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.