Mail API

Since version 4.5 TYPO3 CMS provides a RFC compliant mailing solution, based on SwiftMailer.

Configuration

Several settings are available in the Install Tool (“All Configuration”) affecting the sending process. The most important one is $TYPO3_CONF_VARS[‘MAIL’][‘transport’], which can take the following values:

Value Description
mail Default and backwards compatible setting. This is the most unreliable option. If you are serious about sending mails, consider using “smtp” or “sendmail”.
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:

  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_smtp_server’]: server:port of mailserver to connect to. Port defaults to “25”.
  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_smtp_encrypt’]: Connect to the server using encryption and TLS. Requires openssl library.
  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_smtp_username]: If your SMTP server requires authentication, the username.
  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_smtp_password]: If your SMTP server requires authentication, the password.
sendmail

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

  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_sendmail_command’]: The command to call to send a mail locally. The default works on most modern UNIX based mail server (sendmail, postfix, exim).
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:

  • $TYPO3_CONF_VARS[‘MAIL’][‘transport_mbox_file’]: The file where to write the mails into. Path must be absolute.

Creating mails

This is how to generate and send a mail in TYPO3 (starting with 4.5):

$mail = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Mail\\MailMessage');
$mail->setFrom(array($email => $name))
     ->setTo(array($email => $name))
     ->setSubject($subject)
     ->setBody($body)
     ->send();

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

$mail = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Mail\\MailMessage');
$mail->setFrom(array($email => $name));
$mail->setTo(array($email => $name));
$mail->setSubject($subject);
$mail->setBody($body);
$mail->send();

Adding Attachments

Here a code sample for attaching a file to mail:

     // Create the attachment
     // * Note that you can technically leave the content-type parameter out
$attachment = \Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

     // (optional) setting the filename
$attachment->setFilename('cool.jpg');

     // Attach it to the message
$mail->attach($attachment);

Adding inline media

Here is how to add some inline media (e.g. images) in a mail:

     // Attach the message with a "cid"
$cid = $mail->embed(Swift_Image::fromPath('image.png'));

     // Create a HTML body refering to it
$mail->setBody(
     '<html><head></head><body>' .
             '  Here is an image <img src="' . $cid . '" alt="Image" />' .
             '  Rest of message' .
             ' </body></html>',
     'text/html' //Mark the content-type as HTML
);

Default sender

It is possible to define a default email sender (“From:”) in the Install Tool, with the following settings:

  • $TYPO3_CONF_VARS['MAIL']['defaultMailFromAddress']
  • $TYPO3_CONF_VARS['MAIL']['defaultMailFromName']

To make use of these settings in your extension, use the following code:

$from = \TYPO3\CMS\Core\Utility\MailUtility::getSystemFrom();
$mail = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Mail\\MailMessage');
$mail->setFrom($from);
...

SwiftMailer documentation

For more information about available methods, please refer to SwiftMailer documentation, in particular: