Technical documentation - Mail managers
- Corentin Humbert
- Mattias Löfstrand
Version 5.2 and later.
Different modes
The WebViewer supports different ways of creating and sending emails. The following table describes the three different modes that currently exist.
Name | Identifier | Rendering | Sending |
|---|---|---|---|
Native | native | SMS engine. Supports plain text, HTML and Handlebars. | SMTP server |
External (“SendGrid”) | external | SendGrid renderer. Supports plain text, HTML and Handlebars. | SendGrid email API |
Legacy | legacy | Supports plain text and HTML only. | SMTP server |
The Native mode is the default one. Emails are created by loading templates and rendering them through the SignifikantMailService (SMS).
The External mode, which uses SendGrid by default, has the same rendering capabilities as SMS but sends the email via the SendGrid email API.
The External Mail Manager can be easily overridden to use a custom email service instead of SendGrid.
The Legacy mode is the old way of handling emails and should be avoided. It reads templates from text files and does not support Handlebars.
A new way of handling emails is currently being developed. It aims to fix the flaws of SMS and to improve on some areas.
Key features:
Templates are stored in files so that they are easily editable
Each template has two files: one for HTML content, and one for metadata
Metadata are used to identify templates and register them. This way, it is easy to make an app to interface with the templates and edit them via a beautiful UI.
Rendering engine supports Handlebars and defines custom helpers
Formatting: Convert to uppercase, lowercase, etc.
Logical: Insert current date, translate text and data, etc.
Simplifying the WebViewer by removing all email-related logic to its own project. This will make it easier to maintain the existing code for emails and also reduce the complexity of the WebViewer.
Separating rendering/sending in two different projects. This way, you can still leverage the power of the rendering engine even if you want to implement your own way of sending emails.
Configuration
There are two ways of setting up emails in the WebViewer:
Via the admin configuration panel
In profile.config
Admin configuration panel
In the WebViewer, go to Administrate > Configuration > Mails and you will see the following:
For now, you have access to six different sections:
CompanyConfig: Brand information that appear in the email (header, footer)
Global: You can set the mode for the mail manager here (
native,externalorlegacy).Email Test: Test the mail manager by sending a test email
Advanced: Specific settings for order emails
SMTP: Configuration for the SMTP server. Irrelevant if using the
externalmodeSendGrid: Configuration for SendGrid. Only used in the
externalmode
Verification
Use the UI functionality to send mail from admin pages to verify that the configuration is correct and mails actually sent.
Profile.config
Open up App_Data/<site>/profile.config:
<ProfileSettings>
<CompanySettings>
<Name>Signifikant</Name>
<FullName>Signifikant Svenska AB</FullName>
<Website>https://www.signifikant.se/</Website>
<Country>Sweden</Country>
<LogoUrl>https://www.signifikant.se/wp-content/uploads/2019/09/Logotype-tag-1.svg</LogoUrl>
</CompanySettings>
<MailManagerMode>native</MailManagerMode>
<SmtpClientSettings>
<Host>smtp-mail.outlook.com</Host>
<Port>587</Port>
<EnableSSL>true</EnableSSL>
<UseDefaultCredentials>false</UseDefaultCredentials>
<UseCredentials>true</UseCredentials>
<SenderEmail>example@outlook.com</SenderEmail>
<UserName>example@outlook.com</UserName>
<PassWord>a very secure password 123</PassWord>
</SmtpClientSettings>
<SendGridMailManager>
<SendGridMailManager>
<ApiKey></ApiKey>
<SenderEmail></SenderEmail>
</SendGridMailManager>
</SendGridMailManager>
</ProfileSettings>