Attention

TYPO3 v11 has reached end-of-life as of October 31th 2024 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here: TYPO3 ELTS.

Mail API

New in version 10.0

Symfony mailer and mime support was added with this change: Feature: #88643 - New Mail API based on symfony/mailer and symfony/mime

New in version 10.3

TYPO3 now supports sending template-based emails for multi-part and HTML-based emails out-of-the-box. The email contents are built with the Fluid Templating Engine. Feature: #90266 - Fluid-based email templating

TYPO3 provides a RFC-compliant mailing solution based on symfony/mailer for sending emails and symfony/mime for creating email messages.

TYPO3’s backend functionality already ships with a default layout for templated emails, which can be tested out in TYPO3’s install tool test email functionality.

Table of Contents

Configuration

Several settings are available in the "Configure Installation-Wide Options" $GLOBALS['TYPO3_CONF_VARS']['MAIL'] .

Note

If you want to send emails using Microsoft 365 or Office 365, you have to configure a connector first, as described in the article Configure a connector to send mail using Microsoft 365 or Office 365 SMTP relay.

Format

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['format'] can be both, plain or html. This option can be overridden by Extension authors in their use cases.

Fluid paths

All Fluid-based template paths can be configured via

where TYPO3 reserves all array keys below 100 for internal purposes.

If you want to provide custom templates or layouts, set this in your LocalConfiguration.php / AdditionalConfiguration.php file:

typo3conf/AdditionalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'][700] = 'EXT:my_site_extension/Resources/Private/Templates/Email';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['layoutRootPaths'][700] = 'EXT:my_site_extension/Resources/Private/Layouts';

transport

The most important configuration option for sending emails is $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] , which can take the following values:

smtp

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'smtp';: Sends messages over SMTP. It can deal with encryption and authentication. Works exactly the same on Windows, Unix and MacOS. Requires a mail server and the following additional settings:
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_server'] = '<server:port>';: Mail server name and port to connect to. Port defaults to "25".
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_encrypt'] = <bool>;: Determines whether the transport protocol should be encrypted. Requires openssl library. If false, symfony/mailer will use STARTTLS.

Changed in version 10.4

The allowed values fo this settings has changed (from string to boolean), see Important: #91070 - SMTP transport option 'transport_smtp_encrypt' changed to boolean
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_username] = '<username>';: If your SMTP server requires authentication, the username.
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_password] = '<password>';: If your SMTP server requires authentication, the password.

Example:

typo3conf/AdditionalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'smtp';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_server'] = 'localhost';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_encrypt'] = true;
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_username'] = 'johndoe';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_password'] = 'cooLSecret';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'] = 'bounces@example.org';  // fetches all 'returning' emails

sendmail

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'sendmail';

Sends messages by communicating with a locally installed MTA - such as sendmail. This may require setting the additional option:

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_sendmail_command'] = '<command>';

The command to call to send a mail locally. The default works on most modern UNIX based mail servers (sendmail, postfix, exim).

Example:

typo3conf/AdditionalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'sendmail';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_sendmail_command'] = '/usr/sbin/sendmail -bs';

Attention

Depending on the configuration of the server and the TYPO3 instance, it may not be possible to send emails to BCC recipients. The configuration of the $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_sendmail_command'] value is crucial.

TYPO3 recommends the parameter -bs (instead of -t -i). The parameter -bs tells TYPO3 to use the SMTP standard and that way the BCC recipients are properly set. Symfony refers to the problem of using the -t parameter as well. Since forge#65791 the transport_sendmail_command is automatically set from the PHP runtime configuration and saved. Thus, if you have problems with sending emails to BCC recipients, check the above mentioned configuration.

mbox

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = 'mbox';: This doesn't send any mail out, but instead will write every outgoing mail to a file adhering to the RFC 4155 mbox format, which is a simple text file where the mails are concatenated. Useful for debugging the mail sending process and on development machines which cannot send mails to the outside. The file to write to is defined by:
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_mbox_file'] = '</abs/path/to/mbox/file>';: The file where to write the mails into. Path must be absolute.

<classname>

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = '<classname>';: Custom class which implements \Symfony\Component\Mailer\Transport\TransportInterface. The constructor receives all settings from the MAIL section to make it possible to add custom settings.

validators

New in version 11.0

Using additional validators can help to identify if a provided email address is valid or not. By default, the validator \Egulias\EmailValidator\Validation\RFCValidation is used. The following validators are available:

\Egulias\EmailValidator\Validation\DNSCheckValidation
\Egulias\EmailValidator\Validation\SpoofCheckValidation
\Egulias\EmailValidator\Validation\NoRFCWarningsValidation

Additionally it is possible to provide an own implementation by implementing the interface \Egulias\EmailValidator\Validation\EmailValidation.

If multiple validators are provided, each validator must return true.

Example:

typo3conf/AdditionalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['validators'] = [
   \Egulias\EmailValidator\Validation\RFCValidation::class,
   \Egulias\EmailValidator\Validation\DNSCheckValidation::class
];

Spooling

The default behavior of the TYPO3 mailer is to send the email messages immediately. You may, however, want to avoid the performance hit of the communication to the email server, which could cause the user to wait for the next page to load while the email is being sent. This can be avoided by choosing to "spool" the emails instead of sending them directly.

Spooling in memory

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_type'] = 'memory';

When you use spooling to store the emails to memory, they will get sent right before the kernel terminates. This means the email only gets sent if the whole request got executed without any unhandled exception or any errors.

Spooling using files

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_type'] = 'file';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_filepath'] = '/folder/of/choice';

When using the filesystem for spooling, you need to define in which folder TYPO3 stores the spooled files. This folder will contain files for each email in the spool. So make sure this directory is writable by TYPO3 and not accessible to the world (outside of the webroot).

Additional notes about the mailspool path:

If the path is absolute, the path must either start with the root path of the TYPO3 project or the public web folder path
If the path is relative, the public web path is prepended to the path
Must not contain symlinks (important for environments with auto deployment)
Must not contain //, .. or \

Sending spooled mails

To send the spooled mails you need to run the following CLI command:

vendor/bin/typo3 mailer:spool:send

This command can be set up to be run periodically using the TYPO3 Scheduler.

How to create and send mails

There are 2 ways to send emails in TYPO3 based on the Symfony API:

With Fluid, using \TYPO3\CMS\Core\Mail\FluidEmail
Without Fluid, using \TYPO3\CMS\Core\Mail\MailMessage

\TYPO3\CMS\Core\Mail\MailMessage and \TYPO3\CMS\Core\Mail\FluidEmail inherit from \Symfony\Component\Mime\Email and have a similar API. FluidEmail is specific for sending emails based on Fluid.

Either method can be used to send emails with HTML content, text content or both HTML and text.

Send mail with `FluidEmail`

This sends an email using an existing Fluid template TipsAndTricks.html, make sure the paths are setup as described in Fluid paths:

use Symfony\Component\Mime\Address;
use TYPO3\CMS\Core\Mail\FluidEmail;
use TYPO3\CMS\Core\Mail\Mailer;

$email = GeneralUtility::makeInstance(FluidEmail::class);
$email
    ->to('contact@example.org')
    ->from(new Address('jeremy@example.org', 'Jeremy'))
    ->subject('TYPO3 loves you - here is why')
    ->format(FluidEmail::FORMAT_BOTH) // send HTML and plaintext mail
    ->setTemplate('TipsAndTricks')
    ->assign('mySecretIngredient', 'Tomato and TypoScript');
GeneralUtility::makeInstance(Mailer::class)->send($email);

A file TipsAndTricks.html must exist in one of the paths defined in $GLOBALS['TYPO3_CONF_VARS']['MAIL']['templateRootPaths'] for sending the HTML content. For sending plaintext content, a file TipsAndTricks.txt should exist.

Defining a custom email subject in a custom Fluid template:

<f:section name="Subject">New Login at "{typo3.sitename}"</f:section>

Building templated emails with Fluid also allows to define the language key, and use this within the Fluid template:

$email = GeneralUtility::makeInstance(FluidEmail::class);
$email
    ->to('contact@example.org')
    ->assign('language', 'de');

In Fluid, you can now use the defined language key ("language"):

<f:translate languageKey="{language}" id="LLL:EXT:my_ext/Resources/Private/Language/emails.xml:subject" />

Send email with `MailMessage`

MailMessage can be used to generate and send a mail without using Fluid:

EXT:site_package/Classes/Utility/MyMailUtility.php

// Create the message
$mail = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class);

// Prepare and send the message
$mail

   // Defining the "From" email address and name as an object
   // (email clients will display the name)
   ->from(new \Symfony\Component\Mime\Address('john.doe@example.org', 'John Doe'))

   // Set the "To" addresses
   ->to(
      new \Symfony\Component\Mime\Address('receiver@example.org', 'Max Mustermann'),
      new \Symfony\Component\Mime\Address('other@example.org')
   )

   // Give the message a subject
   ->subject('Your subject')

   // Give it the text message
   ->text('Here is the message itself')

   // And optionally a HTML message
   ->html('<p>Here is the message itself</p>')

   // Optionally add any attachments
   ->attachFromPath('/path/to/my-document.pdf')

   // And finally send it
   ->send()
 ;

Or if you prefer, don't concatenate the calls:

EXT:site_package/Classes/Utility/MyMailUtility.php

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

$mail = GeneralUtility::makeInstance(MailMessage::class);
$mail->from(new Address('john.doe@example.org', 'John Doe'));
$mail->to(
   new Address('receiver@example.org', 'Max Mustermann'),
   new Address('other@example.org')
);
$mail->subject('Your subject');
$mail->text('Here is the message itself');
$mail->html('<p>Here is the message itself</p>');
$mail->attachFromPath('/path/to/my-document.pdf');
$mail->send();

Note

Before TYPO3 v10 the MailMessage class only had methods like ->setTo(), setFrom(), ->setSubject() etc. Now the class inherits from \Symfony\Component\Mime\Email which provides the methods from the example. To make migration from older TYPO3 versions easier the previous methods still exist. The use of MailMessage in own extensions is recommended.

How to add attachments

Attach files that exist in your file system:

EXT:site_package/Classes/Utility/MyMailUtility.php

// Attach file to message
$mail->attachFromPath('/path/to/documents/privacy.pdf');

// Optionally you can tell email clients to display a custom name for the file
$mail->attachFromPath('/path/to/documents/privacy.pdf', 'Privacy Policy');

// Alternatively attach contents from a stream
$mail->attach(fopen('/path/to/documents/contract.doc', 'r'));

How to add inline media

Add some inline media like images in a mail:

EXT:site_package/Classes/Utility/MyMailUtility.php

// Get the image contents from a PHP resource
$mail->embed(fopen('/path/to/images/logo.png', 'r'), 'logo');

// Get the image contents from an existing file
$mail->embedFromPath('/path/to/images/signature.png', 'footer-signature');

// reference images using the syntax 'cid:' + "image embed name"
$mail->html('<img src="cid:logo"> ... <img src="cid:footer-signature"> ...');

How to set and use a default sender

It is possible to define a default email sender ("From:") in the Install Tool:

typo3conf/AdditionalConfiguration.php

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'] = 'john.doe@example.org';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromName'] = 'John Doe';

This is how you can use these defaults:

EXT:site_package/Classes/Utility/MyMailUtility.php

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Utility\MailUtility;
use TYPO3\CMS\Core\Mail\MailMessage;

$from = MailUtility::getSystemFrom();
$mail = GeneralUtility::makeInstance(MailMessage::class);

// As getSystemFrom() returns an array we need to use the setFrom method
$mail->setFrom($from);
// ...
$mail->send();

In case of the problem "Mails are not sent" in your extension, try to set a ReturnPath:. Start as before but add:

EXT:site_package/Classes/Utility/MyMailUtility.php

use TYPO3\CMS\Core\Utility\MailUtility;

// you will get a valid Email Adress from  'defaultMailFromAddress' or if not set from PHP settings or from system.
// if result is not a valid email, the final result will be no-reply@example.org..
$returnPath = MailUtility::getSystemFromAddress();
if ($returnPath != "no-reply@example.org") {
    $mail->setReturnPath($returnPath);
}
$mail->send();

Symfony mail documentation

Please refer to the Symfony documentation for more information about available methods.

Mail API

Configuration

Format

Fluid paths

transport

smtp

sendmail

mbox

<classname>

validators

Spooling

Spooling in memory

Spooling using files

Sending spooled mails

How to create and send mails

Send mail with FluidEmail

Send email with MailMessage

How to add attachments

How to add inline media

How to set and use a default sender

Symfony mail documentation

Send mail with `FluidEmail`

Send email with `MailMessage`