The Mail module enables the sending of emails from within Magnolia CMS. The module can be used to send plain text and HTML messages, template-based messages and Web pages. Other Magnolia CMS modules such as Form and Public User Registration use the Mail module for messaging. You can use FreeMarker to create email templates for newsletters.

• Download
• Installing
• Uninstalling
• Configuring SMTP
• Sending messages
• Plain text and HTML messages
• Template based messages
• Registering a template
• Attachments
• Mixed and related attachments
• Image attachments
• Template renderers
• Example
• HTML page configuration
• Error logging
• Dependent modules
• Form
• Public User Registration
• Observation
• Workflow
• XML file
• Notifications

Download

Download the Mail module from Magnolia Store or Nexus repository.

Installing

Mail is a community module, bundled with both Community and Enterprise Editions, and typically already installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, please see the general module installation instructions.

Uninstalling

See the general module uninstalling instructions and advice.

Configuring SMTP

Configure the mail transfer protocol (SMTP) in modules/mail/config/smtp.

Add your values into the following nodes:

• smtpServer: Name of your mail server.
• smtpUser: SMTP user name.
• smtpPassword: SMTP user's password.
• smtpPort: Default communication port is 25 (simple SMTP).
• To use secure SMTP over SSL (port 465), add a new node titled ssl with value true.
• To use TLS (port 587), add a new node titled tls with value true.

Sending messages

Sending email from Magnolia CMS is typically an automated process. An event acts as a trigger. For example, a verification message is sent to a user when they fill a registration form and a workflow notification is sent to a publisher when a page needs to be activated. The sendMail command registered in /modules/adminInterface/commands/default/sendMail sends the message. It can execute on events such as user actions, workflow steps and scheduled jobs. Write message templates and test them manually in Tools before automating the process for production use.

Plain text and HTML messages

In the Text message configuration section you can send plain text and HTML messages. The fields provided are identical to those of most email applications and clients:

• From: Email address of the sender. Ideally, this email address should correspond to smtpUser and smtpServer properties (main domain portion only) in the /modules/mail/config/smtp, for example john.smith@magnolia-cms.com or youraccount@gmail.com. Regardless of the address entered here, Magnolia CMS will use the smtpUser to send the email but the address here is displayed as the sender to the recipient. This means you can send an email from fake@address.com and it will appear to come from this address.
• To: Recipient's email address. Separate multiple addresses with a semi-colon (;).
• CC: Carbon copy recipient. Separate multiple addresses with a semi-colon (;).
• Subject: Subject of the message.
• Content Type: Plain text or HTML message content. HTML allows you to use HTML markup in the message.
• Attachment: Upload an attachment.
• Message Text: Message body. Depending on the Content Type field, insert the plain text or HTML.

Template based messages

The Template message configuration section allows you to send emails based on a template. A number of sample templates are provided. workflowNotification and pageCommentsNotification are used by the Workflow and Commenting modules. The other templates are provided as samples to demonstrate the functionality.

Example template script written in Freemarker:

<h1>${user}</h1>
    <img src="cid:0001"/>
    This is the path that has been changed: ${path} 

This template script requires two parameters, user and path, that need to be provided in the Parameters box. The parameters are passed to the template script and rendered in the message. Each parameter should be added on a single line in the name=value format. For example:

user=jsmith
path=/my/path

Only registered templates show up in the Select a template dropdown.

Registering a template

Templates are registered in /modules/mail/config/templatesConfiguration. The configuration identifies the location of the template script and instructs Magnolia CMS how to render it.

Template properties:

• templateFile: Mandatory. Relative path to the template script. Save the file to /apache-tomcat/webapps/magnoliaAuthor/templates. Template script can placed anywhere in the webapps folder. For example, if you place the script in /magnoliaAuthor/templates/myMailTemplates the path should be /templates/myMailTemplates/registration.html. If you place it in /magnoliaAuthor: It is only necessary to include the file name registration.html.
• type: Mandatory. Identifies the scripting language used in the template.
• contentType: Type of content for the message body. It is only necessary to include this property for emails based on HTML templates.
• from: Email address that will appear in the From field of the message unless overwritten in Tools > Mail or defined elsewhere such as in one of the reliant modules.
• subject: Subject line of the email unless overwritten in Tools > Mail or defined elsewhere such as in one of the reliant modules.

Attachments

Mixed and related attachments

mimeMultipart: Specifies part of structure of MgnlMultipartEmail where attachments are added.

Values are:

• mixed: Attachment added as standard email attachment.
• related: Attachment shown as inline text. MailAttachments with unspecified (null) values in the mimeMultipart property are treated as "related". MailAttachment does not use Content-ID properties but uses attachment names (not file names).
  

Image attachments

To reference an image, create an attachments child node and define the image properties. For example, the testFreemarker.html template script references <img src="cid:0001"/> and this element is defined in the attachments node. The cid property identifies the attachment as an image (value=img) and the url property sets the URL of the image location.

Template renderers

Template renderers are registered in /modules/mail/config/factory. In the default installation there are four renderers:

• freemarker to render FreeMarker email templates.
• magnolia to render Magnolia web pages in an email and implicitly used by the Mail tool in the HTML page configuration section.
• simple to render simple text emails that do not require a specific scripting language to be parsed.
• velocity To tender Velocity templates.

Example

To register a template:

1. Create a simple template named simpleTemplate.html using Freemarker code.

<html>
  <body>
    <p>Dear ${fullName},</p>
    <p>Please follow this link in order to validate your account: 
    <a href="${href}">Verify your user</a></p>
    <p>Thank you!</p>
  </body>
</html>

2. Save the template to the file system in /apache-tomcat/webapps/magnoliaAuthor/templates/simpleTemplate.html. It does not really matter where you put your template script as long as it is within the webapps folder of a Magnolia instance.

3. The template file is referenced by the templateFile property. Register the new template in the Mail module by creating a new content node simpleTemplate in /modules/mail/config/templatesConfiguration.

4. In Tools > Mail, the new template now appears in the Select Template list and can be used in the same way as the sample templates.

HTML page configuration

The HTML page configuration section allows you to send any Magnolia web page as an email.

To send a page:

1. Browse to a page with Select Page.
2. In Content Type, choose html to send the page content in HTML or text to send the page HTML source code.

Email applications and clients on the market display emails in different ways. The main reason for this is varied support for CSS styles. You can use a web based service such as Mailchimp Inbox Inspector to preview the message in various clients and work towards consistency.

Error logging

When you click the Send mail button a success message "Email successfully sent" or an error message is displayed in the top left corner of the page. In most cases, the error message sufficiently explains the reason for the failure. For example, if you use the testFreemarker example template and fail to include the user parameter you will receive a specific error message to this effect. Not all error messages determine the error's exact source. For example, if the error results from invalid SMTP configuration settings the message will simply be "Error: null".

To find more details about an error:

1. Go to Tools > Log Viewer.
2. Select magnolia-error.log from the drop-down list.
3. Click View.
   The content of the error log is displayed.
4. Go to the last page of the file.
   The most recent error appears at the end of the file. The Magnolia class that caused the error is also included such as info.magnolia.module.mail.commands.MailCommand.

Once the class that caused the error has been established you can get more information about the problem using the debug log. You can set the logging level of detail for each class registered in Magnolia. By default, all Mail module classes are set to INFO level. The DEBUG level allows you find out more information about the source of an error. When you select this option, any errors resulting from the classes with this setting are recorded in the magnolia-debug.log file.

To enable debugging:

1. Go to Tools > Logging.
2. Set the logging level to DEBUG for the class that reported the error.
3. Click Set.

The next step is to recreate the original error. Resend the email as before. This time the error will be logged in the debug log.

To view the debug log:

1. Go to Tools > Log viewer.
2. Select magnolia-debug.log from the list.
3. Click View.
   
   
4. Go to the last page of the file.
   As in the case of the error log, the most recent error is at the end. In the debug log the error message is preceded by a number of entries starting with the word "at".
5. Retrace through the lines starting with "at" until you come across the first line starting with the word "DEBUG". This will usually be on the second-to-last page of the file. The processes that were executed appear between the lines starting with "DEBUG" and the specific exception, such as AuthenticationFailedException. This additional information should tell you where the source of the problem lies.

As errors are logged sequentially, the process above may not solve all errors. Repeat the process on any subsequent classes that show up in the error log once the initial error has been rectified.

After an error is rectified, reset the logging level back to its original setting. In the default installation they will in any case reset to their defaults when you next restart Magnolia.

Dependent modules

Form

The Form module uses the Mail module to send emails. The stkForm page template included in the Standard Templating Kit demonstrates the use of the Form module. All forms have a settings paragraph which determines the behavior of the form. The example /demo-project/service/contact page is based on the Contact Form template. In the settings paragraph, the Email and Confirmation Email tabs are used to specify the form data and a confirmation message should be sent.

Email addresses defined here override those in SMTP configuration. Any valid email addresse can be used. It is possible to use Freemarker tags.

On the Submit settings tab the Track Mail field provides the option to create a record of messages in a CSV file. If enabled, a message will be recorded in the /tomcat/webapps/<webappName>/logs/magnolia-form.log file.

Three form processors, configured in the Form module, ensure that the emails are sent and logged. The processors are registered in /modules/form/paragraphs/form/formProcessors and executed if the corresponding form is submitted.

• sendContactEmail: Sends an email to the address specified in the To field.
• sendConfirmationEmail: Sends a confirmation mail. It first verifies if the Send confirmation checkbox is checked and sends a message to the address specified in the To field. By default, this processor is not enabled. This is the case even if the Send a confirmation email to the submitting user checkbox is checked in the dialog. To enable, add an enabled property to the processor and set its value to true.
• trackEmail: Logs the content of submitted form to magnolia-form.log file if the Track Mail option is checked. By default, this processor is not enabled. This is the case even if the Track Mail option is checked in the dialog. To enable it, add an enabled property to the processor and set its value to true.

Once the trackEmail processor is enabled, the form information will be logged to magnolia-form.log.

To view the log:

1. Go to Tools > Log viewer.
2. Select magnolia-form.log from the list.
3. Click View.

Public User Registration

The Public User Registration (PUR) module relies on the Mail module to send messages necessary for public user registration. Configuration and sending of PUR messages works the same way as in the Form module. All that is necessary is to configure STMP settings in the Mail module.

The stkPublicUserRegistration page template demonstrates how the module uses mail. The /demo-project/members-area/registration page which uses the template allows a public user to create an account. A verification email is generated using Freemarker to to create a unique verification link for double opt-in.

[#assign pur = ctx.pur]
[#assign targetPage ="/demo-project/members-area/
registration/double-opt-in-confirmation.html"?url('ISO-8859-1')]

[#assign href="${pur.baseUrl}/.magnolia/pages/user-validation.html?
userId=${pur.userId}&targetPage=${targetPage}"]
<html>
    <body>
        <p>Dear ${fullName},</p>
        <p>Please follow this link in order to validate 
        your account: <a href="${href}">Verify your user</a>
        </p>
        <p>Thank you!</p>
    </body>
</html>

When the user clicks on the link the new account is verified and user is redirected to a Validation Successful (demo-project/members-area/double-opt-in-confirmation) page. Now the user can sign into the protected area.

The password reminder message is another example. Freemarker tag ${user.password} is used to retrieve the user's password from their profile and write it in the message.

[#assign user = ctx.pur.user]

<html>
    <body>
        <p>Dear ${user.getProperty('title')},</p>
        <p>Your password is <br/>${user.password}<br/></p>
        <p>Please keep it safe.</p>
        <p>Thank you !</p>
    </body>
</html> 

This example sends the password in plain text in email. This is not the most secure way to recover a forgotten password. Consider your privacy requirements.

Observation

The Observation module enables applications to register interest in events or changes to a workspace. Event listeners monitor changes and when a persistent change is detected, a defined response is triggered. Email notifications can only be enabled if both the Mail module and the Observation module are installed. The Observation module provides the functionality but relies on the Mail module to send the messages. In the Mail module, it is only necessary to configure SMTP settings.

The messages sent on the occurrence of an event are configured in the Observation module. See Observation module documentation for how to set up your own listener. In the default installation event listeners are configured in /modules/observation/config/listenerConfigurations.

sendMailOnPageComments is an example of a listener. It sends an email when comments are added to a page.

The message template is registered in the Mail module in /modules/mail/templatesConfiguration/pageCommentsNotification. The template configuration does not contain the from property as this is configured in the listener. The subject property is configured in both modules. The value configured in the listener overrides the value configured in the template. The listener uses the default mailCommand registered in sendMailOnPageComments/listener/command to send the message.

The pageCommentsNotification.ftl template script contains the following Freemarker code:

${model.retrieveUser(path)!"Anonymous"} has posted new comment 
for page <a href="${model.retrievePageLink(path)}">
${model.retrievePageTitle(path)!"Untitled"}</a>.
<br/>
<a href="${defaultBaseUrl}.magnolia/pages/forumModeration.html">
Click here to review the message.</a>

As defined in the template script, the message includes links to the page where the comment was added and to a moderation page.

You can also create your own listener class and specify a command to be executed in case of an event.

Workflow

In the standard installation the Workflow module is configured to send activation notifications to the person responsible for reviewing them. These request are received in the Inbox. Magnolia CMS can additionally, or alternatively, be configured to send workflow notifications by email using the Mail module. The workflow activation process definition is registered in /modules/workflow/config/flows/activation. The value contains the workflow definition.

XML file

A workflow definition is an XML file. It contains process definitions that adhere to the OpenWFE schema.

To edit an workflow definition, go to Tools > Workflow and open the activation workflow. If you scroll through the file you will see two process definitions relating to email notifications that are commented out.

<process-definition name="to-publisher">
  <sequence>
    <!--
    uncomment if you like to use an email notification
    -->
    <!--
    <set field="mailTo" value="group-publishers"/>
    <set field="mailTemplate" value="workflowNotification"/>
    <participant ref="command-sendMail"/>
    -->
    <!-- reset the assignTo field so the editor no longers see the workflow item --> 
    <unset field="assignTo"/>
    <participant ref="group-publishers"/>
  </sequence>
</process-definition>

To activate email notifications, uncomment the relevant sections and Save.

Notifications

When an editor requests the activation of a page, document or data item, a notification is sent to users assigned to the publishers group. If the publisher rejects the activation request, a notification is sent back to the user who requested the activation. The activation process definition refers to two groups: publishers and editors. These groups were created by the Workflow module during installation and their members can be viewed in Security. For workflow email notifications to work correctly, valid email addresses are needed for users. For more information groups, users and roles, see Security.

The mail template workflowNotification is referenced in the workflow definition:

  <set field="mailTemplate" value="workflowNotification"/>
      <participant ref="command-sendMail"/>

The template is registered in modules/mail/config/templatesConfiguration:

And the template script file is inside the mail module JAR file:

<html>
  <head></head>
  <body>
    <h1>Magnolia Workflow Notification</h1>
    <p>This mail has been sent by the Magnolia activation Workflow.</p>
  </body>
</html>