You can now become a hero and support this Blog at GitHub Sponsors or Patreon.

More about support

In TYPO3 v10 the swiftmailer component (GitHub) has been replaced (Patch, Feature RST, Breaking RST) with two symfony components: symfony/mailer (GitHub, official component page) and symfony/mime (GitHub, official component page). This means that the API for sending emails has slightly changed and that extension code that sends emails will most likely need an update. In this post we will have a look on what the new components do and how we can use them in our code. Finally, we will have a look at a new feature built on top of it: FluidEmail, which enables streamlined and unified looking system wide emails including all system emails sent by the TYPO3 core itself.

But first things first.

The new API with symfony/mailer

Although this post will focus on the PHP side of the mail API, a notice from the TYPO3 docs regarding configuration mail sending on the server side:

The new component does not handle the regular PHP function mail() anymore. Instead, it is recommended to switch to sendmail or smtp, which can be configured within the TYPO3 Install Tool or the Settings module for System Maintainers under “Presets” => “Mail”.

All existing installations which still configure mail are migrated to sendmail by automatically detecting the sendmail path in the PHP.ini settings, but should be reviewed on update.

With this out of the way, let's have a look on how to send an email in TYPO3 v10:

use Symfony\Component\Mime\Address;
use TYPO3\CMS\Core\Mail\MailMessage;

    ->from(new Address('', 'Benni'))
    ->to(new Address('', 'Paula Paulson'))
    ->cc(new Address('', 'Paul from Accounting'))
    ->subject('Check Slack ASAP')
    ->text('Hi Paula. I wrote you a slack message.')
    ->html('<h4>Hi Paula.</h4><p>I wrote you a slack message.</p>')

As we see, we still instantiate \TYPO3\CMS\Core\Mail\MailMessage for sending an email. However, MailMessage is extending \Symfony\Component\Mime\Email now. A few things from the example are worth mentioning.

  • The addresses for sender, receiver, reply-to etc. are now best handed over as instances of \Symfony\Component\Mime\Address. This class expects an email address and an optional name as constructor arguments. It will validate the given email address against the RFC 2822 standard and throw an exception if the mail address is invalid. An array containing multiple instances of Address can be passed to the before mentioned methods as well.
  • If the email should be a plain text email (Content-Type: text/plain), we just use $email->text($plainTextContent). For HTML mails (Content-Type: text/html), we use $email->html($htmlContent). If both variants are supplied the email will contain both.
  • $mail->send() will instantiate the class \TYPO3\CMS\Core\Mail\Mailer and send itself. In special cases where it is e.g. necessary to provide a different transport configuration the Mailer could also be instantiated with an implementation of  \Symfony\Component\Mailer\Transport\TransportInterface:
use TYPO3\CMS\Core\Mail\Mailer;

// Retrieve $eventDispatcher preferably through dependency injection
// Available after composer require symfony/google-mailer
$transport = new GmailSmtpTransport('user', 'password');
$mailer = GeneralUtility::makeInstance(Mailer::class, $transport, $eventDispatcher)

Note that the Mailer expects an instance of the EventDispatcherInterface (read more about Events over at PSR-14 Events in TYPO3) as a second argument, which the above code does provide and thus the AfterMailerInitializationEvent will be emitted. If we do not rely on the Event being fired we could omit passing the dispatcher.

Anyway the first way of sending mails should be sufficient most of the times. Also, there is another way available which we will have a look at next: FluidEmail.


FluidEmail - streamline your Emails

With TYPO3 10.3 it has become a lot easier to send emails based on a fluid template. More than that, all emails can now easily share a design and layout including the emails sent by TYPO3s system extensions. The underlying feature is the introduction of the FluidEmail class (Patch, Feature RST).  FluidEmail extends \Symfony\Component\Mime\Email similar to MailMessage as we have seen above.

Emails send with FluidEmail will always use layouts, partials and templates located at the paths configured in


The TYPO3 core comes with a predefined layout at EXT:core/Resources/Private/Layouts/SystemEmail.html that is used by system emails by default. If we supply a custom LayoutPath to our site package we could change the appearance of all system emails at once and use the new layout and style for our custom emails as well. Let's have a look on how to send a FluidEmail:

use TYPO3\CMS\Core\Mail\FluidEmail;
use TYPO3\CMS\Core\Mail\Mailer;

$email = GeneralUtility::makeInstance(FluidEmail::class)
    ->assign('user', $user);
if ($GLOBALS['TYPO3_REQUEST'] instanceof ServerRequestInterface) {

By default, FluidEmail will send a plaintext and a HTML version of the email. This means that we need to provide two fluid templates. In the above example there needs to be a RegistrationSuccessful.html for the HTML content and a RegistrationSuccessful.txt for the plaintext variant. If we want to send an HTML email only, we can do that by setting $email->format(FluidEmail::FORMAT_HTML).

The subject of the email can be provided via $email->subject('subject') or by adding the section "Subject" to the fluid template:

<f:layout name="SystemEmail" />
<f:section name="Title">REGISTRATION SUCCESSFUL</f:section>
<f:section name="Subject">Your registration was successfull</f:section>
<f:section name="Main">
    <h4>Hey there {user.fullName},</h4>
    <p>you have successfully registered for our service. Thank you for your data and welcome on board!</p>

With the default layout shipped by the TYPO3 core the email could look like this. The top half color will depend on the color configured for the backend login in ext:backend. The logo is taken from this configuration as well, if no logo is provided the default is taken as shown in the following screenshot.

Some variables are available by default in the templates of a FluidEmail:

  • {typo3.sitename}
    contains the sitename as defined in $GLOBALS['TYPO3_CONF_VARS']['SYS']['sitename']
  • {}
    contains the configured date format from $GLOBALS['TYPO3_CONF_VARS']['SYS']['ddmmyy']
  • {typo3.formats.time}
    contains the configured time format from $GLOBALS['TYPO3_CONF_VARS']['SYS']['hhmm']
  • {typo3.systemConfiguration}
    contains the extension configuration array $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']
  • {typo3.information}
    contains an instance of \TYPO3\CMS\Core\Information\Typo3Information

Additional variables can be assigned to the template as well, as we did in the example above.

If the current Request object is needed in the template FluidEmail offers a helper method setRequest($request) that assures the NormalizedParams are set properly.

With all of this said it should be easy to update existing code to the new email API and integrate custom layouts for a system wide unified email appearance.

Have fun - and send me an email if information provided in this post is missing, misleading or wrong. Thanks for the support on Patreon and Github Sponsors. It's much appreciated. <3


Further Information