Ext: sg_mail

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_mail

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_mail

TYPO3 version: >7.6

About

This extension provides an email templating service and mail queue functionality for all your TYPO3 extensions. It also supports Templates in various languages, which can be managed in the backend.

Additionally sg_mail provides a finisher class for the Formhandler extension, making it possible to manage its templates in the backend.

Usage

Registering your Extension

To make sg_mail available for your extension, you have to register it inside your ext_localconf.php by supplying a path string to an implementation of SGalinski\SgMail\Service\RegisterInterface with:

• your extension key
• a name for the template
• the path to your default template files (template files should be named language_code.template.html. Example: en.template.html)
• a brief description of the template (when is it used ?)
• the template markers(placeholder variables)
• the subjects for all templates. Here you have to use an associative array language_code => subject

Example :

A fully working example class can be found here: SGalinski\SgMail\Example\Register

All you need to do to get the example to work is registering your class in ext_localconf.php with:

\SGalinski\SgMail\Service\MailTemplateService::registerByFile('SGalinski\SgMail\Example\Register');

Send an email with the MailTemplateService

Basic Usage:

1. Get an instance of MailTemplateService
2. Set all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.)
3. Invoke the sendEmail() function

Example:

// get an instance of the service
/** @var MailTemplateService $mailService */
$mailService = $this->objectManager->get(MailTemplateService::class);

// set the extension key & template name (mandatory!)
$mailService->setExtensionKey('your_extension_key');
$mailService->setTemplateName($this->settings['templateName']);

// set all the custom fields, these fields all have fallbacks from your configuration or the code
$mailService->setFromName($this->settings['fromName']);
$mailService->setFromAddress($this->settings['fromEmail']);
$mailService->setToAddresses([$emailAddress]);
$mailService->setIgnoreMailQueue(TRUE);
$mailService->setMarkers(['link' => $uri]);

// set the proper language for the mail
$mailService->setLanguage($GLOBALS['TSFE']->config['config']['language']);

// finally send the mail
$mailService->sendEmail();

The mail queue

The mail queue holds all the mails that have been sent or should be sent in the future. You can view the mail queue in the backend module and interact with the entries.

You can set the priority (setPriority function of the service) for your mails with the constants of the SGalinski\SgMail\Domain\Model\Mail class. With the Flag ignoreMailQueue you can switch between queueing your Mail(false) or immediately(true) sending it.

• PRIORITY_LOWEST
• PRIORITY_LOW
• PRIORITY_MEDIUM
• PRIORITY_HIGH
• PRIORITY_HIGHEST

The higher the priority, the more likely the mail will get send immediately (depending how "busy" the MailQueue is).

The command controller

To enable the mail queue functionality you need to configure the SendMailCommandController.

Go to your scheduler module in the TYPO3 Backend and setup a scheduled CommandController task. Chose the SgMail SendMail:runSendMail CommandController command and supply a frequency in seconds or cron format.

For more information on the TYPO3 scheduler extension read its manual.

Using sg_mail with Formhandler

In your setup.txt of your formhandler extension, you have to invoke the FormhandlerFinisherService of sg_mail. This is done in a similar fashion as with the usual finisher classes.

Example

finishers {
	1 {
		class = SGalinski\SgMail\Service\FormhandlerFinisherService
		config {
			checkBinaryCrLf = message
			template_key = your_template
			extension_key = extension_key
			to_address = admin@sgalinski.de
			from_address = info@sgalinski.de
			from_name = sgalinski.de
			ignore_mail_queue = TRUE
		}
	}
}

The Backend Module

With this extension comes a new module in the "WEB" section of your TYPO3 Backend.

Clicking on it loads the administration panel for all your mail templates and the mailing queue.

The module provides two modes:

In the Template Editor mode you see an overview of all the template markers for the selected template. Here you can edit & reset your templates in all the languages of your TYPO3 instance. Additionally you can test your mails by entering an email address and clicking Send Test Mail.

With the Mail Queue mode, you can see the current content of your mailing queue. For each queue entry you have the following options:

Edit
Disable/Enable
Delete
Show further information
Show history
.... Expand/Collapse the options menu
Send the mail again (if already sent)
Send this mail (if not already sent)
View the content of this mail

Developer Guide

Database and Models

This extension uses two database tables:

• tx_sgmail_domain_model_template

  Stores all template settings that have been provided via the backend module. The Default settings exist only in the register array and not in the database.

• tx_sgmail_domain_model_mail

  This table holds all the mails in the mailing queue. When they are sent, the flag sent is set to true and the sending_time is inserted. You can inspect the mailing queue with the backend module. If an email should ignore the mail queue, it is still inserted in this table with the sent flag set to true.

The extbase model classes for these tables are located at the Domain\Model folder.

Service Classes

Register Interface

To register your extension you need at least one implementation of this interface. Inside the init() function of your Implementation you should define variables for the following purposes:

Template Key

A unique Identifier for this particular template. It should be obvious from the template key for what purpose this template is intended.

Extension Key

The extension key of the TYPO3 extension registering with sg_mail. This should be the same for all of your extensions!

Description

A brief description about the template, visible in the backend module

subject

The default subject text for the emails. It is possible to specify language specific texts with an associative array:

[
	'en' => 'english subject',
	'de' => 'german subject',
	...
]

markers

This is an array of information for substitute variables that are used to replace certain values at runtime.

Each Array element should be its own array and structured like this:

[
	'marker' => 'marker_name',
	'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING,
	'value' => 'some value',
	'description' => 'This marker is used for X in the email'
]

marker = the variable name you use in the template type = the date type of the variable value = an example value, visible in the backend to the editors description = a brief description for what this variable is intended for

Finally you have to call the function \SGalinski\SgMail\Service\MailTemplateService::registerTemplate (this is only marked deprecated for public use) inside your register() function and pass all the necessary values.

Now you can register the class in your ext_localconf.php with

\SGalinski\SgMail\Service\MailTemplateService::registerByFile('SGalinski\SgMail\Example\Register');

You find a complete example of this process in the file SGalinski\SgMail\Example\Register

MailTemplateService

This class provides you with an API to the mailing functionality and various helper functions regarding the your templates.

Here is an overview of some important functions:

function registerTemplate

A static function that adds your template to the service. Should be called from within your Register class (see RegisterInterface).

function registerByFile

Registers a template by providing a complete class name of your RegisterInterface implementation as an argument. Needs to be called from within your ext_localconf.php.

function getDefaultTemplateMarker

Reads custom example template marker from your locallang.xlf. This is only useful if you need multi language examples in your Backend Marker

function getRegisterArray

Returns an array of all registered templates, with each element in the following format:

[
	'templatePath' => '/path/to/template',
	'description' => 'description of the template',
	'marker' => $arrayOfMarkers,
	'extension' => 'extension_key',
	'templateName' => 'unique_template_name',
	'subject' => 'The mail subject',
	'usage' => 'optional description of this templates usage'
]

function loadPredefinedValuesForTemplate

Sets the predefined values for this template that have been supplied by the editor. Use this method if you have no custom values for cc, bcc, replyTo, fromMail and fromName. Returns false if the template & extension key combination was not found.

function sendEmail

Sends your mail or adds it to the mailing queue, depending on the settings. You can specify in with the boolean parameter if the preview values should be used or not.

function sendMailFromQueue

Forces the sending of an E-Mail from within the queue. If it has already been sent, it gets send again.

function setRegisterArray

Enables you to overwrite the register array. This overwrites ALL registered templates with the supplied data and should be handled with care.

function addAttachment

With this function you can add attachments to your mail. The attachment must be of type Swift_OutputByteStream. You must also specify the content-type of the attachment.

function getMailMessage

You can get the instance of \TYPO3\CMS\Core\Mail\MailMessage that is internally used by the service, if you want a more direct interaction with the mail object.

functions setX

Sets the various variables to the supplied values. With these functions you can overwrite for instance from/cc/bcc Adresses, from name etc.

You can also tell the MailTemplateService to not ignore this mail when adding to the mailing queue: function setIgnoreMailQueue.

FormhandlerFinisherService

This class is an implementation of the Typoheads\Formhandler\Finisher\AbstractFinisher Class that is used by the extension formhandler extension.

TypoScriptSettingsService

This Service enables you to access your typoscript settings outside of your controller classes. You simply need to supply your page id and the extension key. If you have no page id specific settings, set the page id to 0.