Variable Fluid Emails in the TYPO3 Form Framework

The TYPO3 Form Framework currently provides four email templates, which you can find in the directory typo3/sysext/form/Resources/Private/Frontend/Templates/Finishers/Email/:

• Default.html
  The new Fluid template in HTML format
• Default.txt
  The new Fluid template in plaintext format
• Html.html
  The old template in HTML format
• Plaintext.html
  The old template in plaintext format

For newly created and already existing forms, the old template versions will be used by default. This behavior allows you to continue using your already customized mail templates for the time being when upgrading an existing TYPO3 project.

To use the new Fluid templates, activate the checkbox "Use FluidEmail" found in the finisher options. The form definition will look like this:

finishers:
  -
    options:
      useFluidEmail: true
      subject: 'E-Mail from website'
      senderAddress: '{email}'
      senderName: '{lastname}'
      attachUploads: true
      recipients:
        info@example.com: 'ACME Inc.'
      addHtmlPart: true
    identifier: EmailToReceiver

TYPO3 offers multiple ways to configure new template paths. These have advantages and disadvantages.

This configuration applies to all emails sent with TYPO3.

The registration is done either via LocalConfiguration.php or AdditionalConfiguration.php in the typo3conf/ directory, or via ext_localconf.php of your sitepackage (or your extension).

The numeric array keys below 100 are reserved in TYPO3 for internal purposes.

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'][100] = 'EXT:your_extension/Resources/Private/Templates/Email';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['layoutRootPaths'][100] = 'EXT:your_extension/Resources/Private/Layouts/Email';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['partialRootPaths'][100] = 'EXT:your_extension/Resources/Private/Partials/Email';

Advantages:

• One-time configuration. All mail finishers in your forms will automatically take these paths into account.
• It is still possible to assign a different template to individual finishers (explained below).

Disadvantage:

• This really is a global configuration. If you setup a Fluid layout with the default name "SystemEmail" this way, it will be used for all emails sent with TYPO3 (e.g. Backend login, passwort reset, …). Depending on the project, this may not be desirable.
  To avoid this, you could rename your copied layout to "FormEmail" and reference it accordingly in the mail templates with <f:layout name="FormEmail" />.

You can also specify the paths directly in the mail finisher within the form definition:

finishers:
  -
    options:
      useFluidEmail: true
      templateRootPaths:
        100: 'EXT:your_extension/Resources/Private/Templates/Email/'
      layoutRootPaths:
        100: 'EXT:your_extension/Resources/Private/Layouts/Email/'
      subject: 'E-Mail from website'
      senderAddress: '{email}'
      senderName: '{lastname}'
      attachUploads: true
      recipients:
        info@example.com: 'ACME Inc.'
      addHtmlPart: true
    identifier: EmailToReceiver

Advantages:

• No interference with system emails.
• Template paths can be purposefully assigned to an email finisher.

Disadvantage:

• Email finishers without this option will continue to use the system default.

You can add template paths in the YAML configuration of both email finishers:

TYPO3:
  CMS:
    Form:
      prototypes:
        standard:
          finishersDefinition:
            EmailToReceiver:
              options:
                templateRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Templates/Email/'
                layoutRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Layouts/Email/'
                partialRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Partials/Email/'
              # Optional: Enable FluidEmail for all newly added email finishers:
              formEditor:
                predefinedDefaults:
                  options:
                    useFluidEmail: true
            EmailToSender:
              options:
                templateRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Templates/Email/'
                layoutRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Layouts/Email/'
                partialRootPaths:
                  20: 'EXT:your_extension/Resources/Private/Partials/Email/'
              formEditor:
                predefinedDefaults:
                  options:
                    useFluidEmail: true

You extend the form configuration with a YAML file in your site package. The setup is explained in this tutorial.
Starting with TYPO3 v12, the first three lines with the namespace TYPO3.CMS.Form can be removed.

Advantages:

• No interference with system emails.
• The template paths are considered for all email finishers used in form definitions.
• You can still overwrite these paths for a single email finisher in a form definition.

In my opinion, a combination of methods 2 and 3 is most suitable:

• Register new paths for the email finishers in the YAML configuration. These will then apply to all emails sent via EXT:form, but not to system emails.
• If needed, override these paths for individual emails in the form definitions.

I also suggest that you do not create a new path for each possible template. Instead, you should use the possibility to set a template name in the finisher and store the different templates in a single or a few directories:

finishers:
  -
    options:
      # A template with this name will be searched
      # in all configured templateRootPaths:
      templateName: Newsletter
      useFluidEmail: true
      subject: 'E-Mail from website'
      senderAddress: '{email}'
      senderName: '{lastname}'
      attachUploads: true
      recipients:
        info@example.com: 'ACME Inc.'
      addHtmlPart: true
    identifier: EmailToReceiver

The detailed questions will then depend on your customer project: do you configure two directories with different default templates for sender and receiver? Or do you have a multi-domain installation in which several subsidiaries should each receive their own email layout? Should editors (with no possibility to edit YAML directly) be able to configure new forms?

By combining the above-mentioned possibilities, it should be possible to find a reasonable structure for every use case.

If you want to use a global fluid layout for all system emails: extend only layoutRootPaths via $GLOBALS['TYPO3_CONF_VARS'] and define the templateRootPaths via YAML.

After we configured the paths, we now can copy the email templates from the TYPO3 core to the defined directory. The following checklist clarifies what may need to be taken into account.

Which templates do I need to copy?

As mentioned above, the email templates for forms are located in the directory typo3/sysext/form/Resources/Private/Frontend/Templates/Finishers/Email/.

Relevant for FluidEmail are Default.html and Default.txt.

Do I need both templates (HTML and plain text)?

Not necessarily. If you want to send emails in only one of the two mail formats, you can configure this in LocalConfiguration.php with $GLOBALS['TYPO3_CONF_VARS']['MAIL']['format'] (both/html/plain).

Do I need to copy and customize the Fluid layout as well?

Not necessarily. The layout already uses the logo and background color configured for the backend login screen (Admin Tools > Settings > Extension Configuration > Backend > Login).

However, you probably want to replace the default footer ("This email was sent by ..." and the copyright notice) in the emails. And these texts are not variables but hard-coded in the layout.

What do I have to consider when customizing the "SystemEmail" layout?

The following problem seems to affect TYPO3 v10 only. I could not reproduce it in TYPO3 v11.

The "SystemEmail" layout is used for all emails sent from the TYPO3 core. In some cases, emails will be sent without a frontend context, e.g. when reporting a successful backend login (User Preferences > "Notify me by email when somebody logs in from my account"). This results in an error message if you use an f:translate Viewhelper in the fluid layout:

"Return value of TYPO3\CMS\Extbase\Utility\LocalizationUtility::getLanguageService() must be an instance of TYPO3\CMS\Core\Localization\LanguageService, null returned"

As soon as you want to use localized texts in the email layout, you must therefore limit the use of the fluid layout in question:

• Either: Save your "SystemEmail" layout under a new name and reference it in the fluid templates with <f:layout name="MyNewLayout" />.
• Or: Configure layoutRootPaths not globally, but specifically for the TYPO3 Form Framework (and maybe for other frontend plugins like EXT:felogin).

Where can I find the mail layout?

The main fluid layout for emails is located in the directory typo3/sysext/core/Resources/Private/Layouts/.

The Form Framework now uses your customized email template. But the sent emails will still all be identical in design and content. There may be cases where this is not desired, such as:

• The emails to sender and receiver should receive different templates, for example with different mail texts.
• The emails of your newsletter form need different texts and a different look than those of the contact form.

No problem! You can specify a different, self-selected templateName in the mail finisher:

finishers:
  -
    options:
      templateName: Newsletter
      useFluidEmail: true
      subject: 'E-Mail from website'
      senderAddress: '{email}'
      senderName: '{lastname}'
      attachUploads: true
      recipients:
        info@example.com: 'ACME Inc.'
      addHtmlPart: true
    identifier: EmailToReceiver

In that case, TYPO3 needs the templates Newsletter.html and Newsletter.txt in the same directory as your customized Default.html.

With the additional "Newsletter" template you can adapt the content of the email. However, the default design is still used. In the f:layout Viewhelper of your email template, enter the desired name of your new Fluid layout, e.g. "NewsletterDesign":

Newsletter.html:

<f:layout name="NewsletterDesign" />

<f:section name="Title">{title}</f:section>
<f:section name="Main">
    <!-- Mail content -->
</f:section>

Then, add NewsletterDesign.html and NewsletterDesign.txt with your new design in Resources/Private/Layouts/Email/.