README.md

#  Ext: sg_mail 

<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_routes

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

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.

## The Backend Module

After a successful Installation, you have a new module in the "WEB" section of your TYPO3 Backend. 

Clicking on it loads the administration panel. Here you can create, update, delete and test your E-Mail templates.


## 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

You can also 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).

## Using sg_mail with Formhandler

In your **setup.ts** 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
			}
		}
}
```


## Developer Guide

### Service Classes
#### RegisterInterface
#### MailTemplateService
#### FormhandlerFinisherService
#### TypoScriptSettingsService

## Database and Models

### The mail queue

#### The command controller