sandstorm / templatemailer
Neos and Flow package for simple handling of template-based emails, including CSS inlining
Installs: 39 900
Dependents: 2
Suggesters: 0
Security: 0
Stars: 11
Watchers: 8
Forks: 14
Open Issues: 1
Type:neos-package
Requires
- neos/flow: ^7.3 || ^8.0 || dev-main
- neos/swiftmailer: ^7.0
- pelago/emogrifier: ^6.0 || ^7.0
README
Features
This package works in Neos CMS and Flow and provides the following functionality:
- Simple creation and sending of Fluid template-based emails
- Automatic inlining of CSS into the email body, making it look good in clients like Gmail as well
Compatibility and Maintenance
Sandstorm.TemplateMailer is currently being maintained for the following versions:
Configuration and Usage
Configuring SwiftMailer
The TemplateMailer package requires SwiftMailer to send out e-mails. Please check the swiftmailer package's configuration options (https://github.com/neos/swiftmailer) in order to configure SMTP credentials.
Configuring the package
This package provides 2 config options.
Configuring global sender addresses
By adding entries to the senderAddresses
config array, you can define sender addresses
in your config and connect them to a string identifier. This allows for easy global maintenance
of email sender addresses and names. Override the "default" entry to just have one global
sender address that's automatically used everywhere without you having to do anything else.
Sandstorm: TemplateMailer: senderAddresses: yourGlobalSender: name: 'Foo Bar' address: 'baz@example.com'
Configuring global reply to addresses
By adding entries to the replyToAddresses
config array, you can define reply to addresses
in your config and connect them to a string identifier. This allows for easy global maintenance
of email reply to addresses and names. By default, no reply to address is used. To set a reply to address
on the mail, you need to specify the reply to address key as method argument of sendTemplateEmail
.
Sandstorm: TemplateMailer: replyToAddresses: yourGlobalReplyTo: name: 'Foo Bar' address: 'baz@example.com'
Configuring template source packages
You need to tell TemplateMailer in which packages it should look for email templates. Do this by adding an
entry to the templatePackages
array, like so:
Sandstorm: TemplateMailer: templatePackages: 10: 'Your.Package'
If you have multiple packages that contain email templates, add them all in the order you want TemplateMailer to search them for templates. Lower numbers as keys mean that this package is checked earlier. If a template with the given name is found in a package, it is used. This way, you can create an override hierarchy.
Default Template Variables
You can expose configuration settings as default template variables to all email templates. We use this to expose the base Uri by default, but you can pass arbitrary settings paths here and they will be resolved.
Sandstorm: TemplateMailer: defaultTemplateVariables: baseUri: 'Neos.Flow.http.baseUri'
Logging errors and sent mails
You can control how TemplateMailer handles errors and also successfully sent mails via the two parameters in logging
.
Via the "sendingErrors" config option, you can specifiy what templateMailer should do if the email could not be sent correctly.
There are three options:
- 'throw' -> throws the exception which came from SwiftMailer if sending failed
- 'log' -> logs a message to the system log if sending failed
- 'none' -> silently swallow errors without logging or throwing them
For "sendingSuccess", you can only select 'log' or 'none'. 'log' will insert a log entry for all sent emails. Since this can create lots of entries in your log file, use it for debugging/monitoring purposes only.
Sandstorm: TemplateMailer: logging: sendingErrors: 'log' sendingSuccess: 'log'
Using the package
Create an "EmailTemplates" folder in your package's Resources/Private
folder. In it, create as many email templates as
you want.
IMPORTANT: You must create a .txt and an .html file with the same name for each template-based mail you want to send.
You can use partials and layouts as usual in Fluid. If you do, put them in Resources/Private/EmailTemplates/Partials
or Resources/Private/EmailTemplates/Layouts
respectively.
Basic usage
A very basic usage without variables looks like this. Your template must not contain any variables (as you aren't passing in any) and TemplateMailer will use the "default" sender address, which you should configure beforehand.
$this->emailService->sendTemplateEmail( 'YourTemplateFileName', 'An arbitrary email title', ['recipient@example.com'] );
Globally configured custom sender address
You can use a different configured sender address as well as pass variables to the template. You need to have configured the sender email 'mysender' before.
$this->emailService->sendTemplateEmail( 'YourTemplateFileName', 'An arbitrary email title', ['recipient@example.com'], [ 'var1' => 'Foo', 'var2' => 5 ], 'mysender' );
Dynamic sender address
If you pass an array to the sendTemplateEmail()
method, we'll pass it right through to SwiftMailer so you can
use sender email addresses that haven't been configured before.
$this->emailService->sendTemplateEmail( 'YourTemplateFileName', 'An arbitrary email title', ['recipient@example.com'], [ 'var1' => 'Foo', 'var2' => 5 ], ['sender@example.com' => 'Your Service Name'] );
CC, BCC and Attachments
You can also set cc, bcc and attachments. Here is a full example:
$this->emailService->sendTemplateEmail( 'YourTemplateFileName', 'An arbitrary email title', ['recipient@example.com'], [ 'var1' => 'Foo', 'var2' => 5 ], 'mysender', ['cc@example.com', 'cc2@example.com'], ['bcc@example.com'], [ [ 'data' => file_get_contents('some/example/file'), 'filename' => 'YourFileNAme.pdf', 'contentType' => 'application/pdf' ] ] );