1.. include:: ../../Includes.txt
2
3==============================================
4Feature: #90266 - Fluid-based email templating
5==============================================
6
7See :issue:`90266`
8
9Description
10===========
11
12TYPO3 now supports sending template-based emails for multi-part and HTML-based
13emails out-of-the-box. The email contents are built with Fluid Templating Engine.
14
15TYPO3's backend functionality already ships with a default layout
16for templated emails, which can be tested out in TYPO3's install tool test email functionality.
17
18It is also possible to set a default mode for sending out emails via :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['format']`
19which can be :php:`both`, :php:`plain` or :php:`html`.
20
21This option can however overridden by Extension authors in their use cases.
22
23All Fluid-based template paths can be configured via
24
25:file:`LocalConfiguration.php`:
26
27* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['layoutRootPaths']`
28* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['partialRootPaths']`
29* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths']`
30
31where TYPO3 reserves all array keys below :php:`100` for internal purposes. If you want to provide custom templates or layouts,
32set this in your :file:`LocalConfiguration.php` / :file:`AdditionalConfiguration.php` file:
33
34* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'][700] = 'EXT:my_site_extension/Resources/Private/Templates/Email';`
35* :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['layoutRootPaths'][700] = 'EXT:my_site_extension/Resources/Private/Layouts';`
36
37In addition, it is possible to define a section within the Fluid template,
38which - if set - takes precedence over the :php:`subject()` method.
39
40Impact
41======
42
43TYPO3 now sends out templated messages for system emails in both plaintext and HTML format.
44
45It is possible to use the same API in your custom extension like this:
46
47.. code-block:: php
48
49   $email = GeneralUtility::makeInstance(FluidEmail::class);
50   $email
51       ->to('contact@acme.com')
52       ->from(new Address('jeremy@acme.com', 'Jeremy'))
53       ->subject('TYPO3 loves you - here is why')
54       ->format('html') // only HTML mail
55       ->setTemplate('TipsAndTricks')
56       ->assign('mySecretIngredient', 'Tomato and TypoScript');
57   GeneralUtility::makeInstance(Mailer::class)->send($email);
58
59Defining a custom email subject in a custom template:
60
61.. code-block:: html
62
63   <f:section name="Subject">New Login at "{typo3.sitename}"</f:section>
64
65Building templated emails with Fluid also allows to define the language key,
66and use this within the Fluid template:
67
68.. code-block:: php
69
70   $email = GeneralUtility::makeInstance(FluidEmail::class);
71   $email
72       ->to('contact@acme.com')
73       ->assign('language', 'de');
74
75.. code-block:: html
76
77   <f:translate languageKey="{language}" id="LLL:my_ext/Resources/Private/Language/emails.xml:subject" />
78
79.. index:: Fluid, ext:core
80