Newer
Older
<img src="https://www.sgalinski.de/typo3conf/ext/project_theme/Resources/Public/Images/logo.svg" />
License: [GNU GPL, Version 2](https://www.gnu.org/licenses/gpl-2.0.html)
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](https://typo3.org/extensions/repository/view/formhandler) extension, making it possible to manage its templates in the backend.
sg_mail ist multi-site and multi-language ready.
## Usage
### Registering your Extension
To register your extension with sg_mail, you need a **Configuration File** for each template you want to integrate.
It needs be a *.php* file and has to be inside the Configuration folder **typo3conf/ext/{your_extension}/Configuration** of your extension.
The naming of the file should be in upper camel case, matching your template name.
sg_mail will automatically parse valid configuration files of all extensions within your TYPO3 instance.
Inside the file you have mandatory and optional settings you can define:
- extension_key
Needed to associate this template with the appropriate extension,
- template_key
A unique identifier of your template.
- description
A short description of your templates usage, displayed in the backend template editor. This should be a **language label**
- subject
The default mail subject used for this Template. Here you can also provide a language label.
An array of placeholder variables. Are dynamically replaced by the appropriate values. If you don't want any markers, provide an empty array.
A marker needs to be structured as follows:
- marker
The variables name used in your templates.
- type
Here you can specify the variable type by using one of the constants in the **\SGalinski\SgMail\Service\MailTemplateService** class.
- value
An example value of this marker. Also used for previewing your mails in the backend module.
- description
A short text describing the purpose of this marker.
**Optional**
- template_path
You can provide a path to your mail template that differs from the default path with this setting.
**The template folder**
If not overwritten in your configuration file, the default location for your extensions templates is **ext/sg_example/Resources/Private/Templates/SgMail/{TemplateNameInUpperCamelCase}**.
Inside this folder you need a folder for every template you want to register. The name of the template file itself should be **template.html**
Your configuration file for the template "confirm_mail" should be located at **../Configuration/ConfirmMail.php**.
A possible ConfirmMail.php file could look like this:
return [
'extension_key' => 'sg_example',
'template_key' => 'confirm_mail',
'description' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.description',
'subject' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.subject',
'markers' => [
[
'marker' => 'username',
'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING,
'value' => 'max.mustermann@example.org',
'description' => 'LLL:EXT:sg_energieportal/Resources/Private/Language/locallang.xlf:mail.marker.username'
],
.... // more markers
]
];
The default path to the template.html file: ext/sg_example/Resources/Private/Templates/SgMail/ConfirmMail
### Send an email with the MailTemplateService
Basic Usage:
1. Get an instance of MailTemplateService
2. Provide the **template_name**, **extension_key** and marker array in the constructor
3. Set or override all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.)
4. Invoke the **sendEmail()** function
Example:
// get an instance of the service
/** @var MailTemplateService $mailService */
$mailService = $this->objectManager->get(MailTemplateService::class, 'confirm_mail', sg_example', ['username' => $username]);
$mailService->setFromName($this->settings['fromName']);
$mailService->setFromAddress($this->settings['fromEmail']);
$mailService->setToAddresses([$emailAddress]);
$mailService->setIgnoreMailQueue(TRUE);
// set the pageId (mandatory since version 4.0!!!)
$mailService->setPid(123);
// set the proper language for the mail (not necessary if you want the default language)
$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](https://en.wikipedia.org/wiki/Cron) format.
For more information on the TYPO3 scheduler extension read its [manual](https://docs.typo3.org/typo3cms/extensions/scheduler/Index.html).
## Language handling
When you provide no language to the MailService API, the default language of the TYPO3 instance is used.
This happens also if the given iso code of the language is not known (inside the **sys_lang** table).
In your template editor you have automatically all languages of your page shown.
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.
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
}
}
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
## 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:
<img height="20px" width="20px" src="https://camo.githubusercontent.com/e3de477db4caba47f3adc70db73b401be474ec23/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d6f70656e2e737667"> Edit
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/3c5e6daff1f31fd3c4bf0ac3e70520133d06441c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d686964652e737667"> Disable/Enable
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/7773a0fc11517dc70b81f9ba516991f3669493e1/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d656469742d64656c6574652e737667"> Delete
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/ee057cb37045beeccf8078f74e65e1774ec5e001/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d696e666f2e737667"> Show further information
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/91c383d7beded93dbe6a62e2a1ae94bf82d1d783/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d686973746f72792d6f70656e2e737667"> Show history
<br>
.... Expand/Collapse the options menu
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/53fd52618f310e4c31cca5a57df3b314bd0a7a9c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d696e736572742d7265666572656e63652e737667"> Send the mail again (if already sent)
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/53fd52618f310e4c31cca5a57df3b314bd0a7a9c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d696e736572742d7265666572656e63652e737667"> Send this mail (if not already sent)
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/4b1188209e740e17a4ec0cd6583425696809017b/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d766965772e737667"> View the content of this mail
Additionally you can now filter the mail queue or export it to a csv file.
## Known Facts
### Countries aren't respected yet. Currently just languages are used.
### 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.
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 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 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.
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.
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.
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](https://typo3.org/extensions/repository/view/formhandler).
#### 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.