Mail module

The Mail module enables the sending of emails from within Magnolia. The module can be used to send plain text and HTML messages, and template-based messages.

Sending emails from Magnolia 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.

Other Magnolia modules such as Form, Observation and Public User Registration use the Mail module for messaging.

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.

Configuration

The Mail module is configured in /modules/mail. Besides configuring SMTP settings the module is ready to use.

Mail command

MailCommand is used to send all mails in Magnolia. The command can execute on events such as user actions, workflow steps and scheduled jobs. You can write message templates and test them manually in Tools > Mail before automating the process for production use.

The command is registered in /modules/adminInterface/commands/default/sendMail.

Configuring SMTP

To configure the default transfer protocol (SMTP) settings go to Configuration > Mail (SMTP). This is a shortcut to /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 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 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

Text message configuration allows you to 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.
• 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.
• Attachment: Upload an attachment.
• Message Text: Message body. Depending on the Content Type field, insert the plain text or HTML.

Template based messages

Template message configuration allows you to send emails based on a template. Message templates are typically used by forms on pages to send the data to the user who submitted the form. Use the tool to test them.

To send a test message:

• Select a template in the dropdown. Only registered templates show up in the dropdown. See Templates configuration for more information.
• Enter test data. The content depends on the template configuration.
• Click Send mail.

Sending pages

Html page configuration allows you to email a Magnolia page.

To email a page:

• Select html content type.
• Select the internal page.
• Enter a valid username and password, if the page is not accessible to the anonymous user.
• Click Send mail.

Templates configuration

Templates are configured in the /modules/mail/config/templateConfiguration folder. The testFreemarker template is provided as an example.

MailTemplate allows for a number of configuration nodes and properties. The following are the most commonly used:

• Properties:
  
  • templateFile: Mandatory. Relative path to the template script. 
  • type: Mandatory. Scripting language used in the template.
  • contentType: Type of content for the message body. It is only necessary to include this property for HTML emails.
  • from: Email address that will appear in the From field of the message, unless defined elsewhere, for example in Form module.
    subject: Subject line of the email, unless defined elsewhere for example in the Form module.
• Nodes:
  • attachments: MailAttachment provides for a number of attachment options. 

  • parameters: Any parameters to be passed to the script.

Template scripts

Here's the example testFreemarker.html (GIT) template script.

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

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

user=jsmith
path=/my/path

Attachments

In the attachments node you can define properties for the parameters called by the script. For example, the testFreemarker.html template script references img src="cid:0001". The cid property identifies the attachment as an image (value={}) and the url property sets the image location.

The mimeMultipart property can be used to define the structure of a MgnlMultipartEmail:

• mixed: Standard email attachment.

• related: Attachment shown inline. This is the default when no mimeMultipart property is speciied. MailAttachment does not use Content-ID properties but uses attachment names (not file names).

Template renderers

Template renderers are referenced in the type property of the template configuration. Renderers are registered  in /modules/mail/config/factory/renderers:

• freemarker: To render Freemarker email templates.
• magnolia: To render Magnolia web pages in an email.

• simple: To render simple text emails that do not require a specific scripting language to be parsed.

• velocity: To render Velocity email templates.

Creating a custom template

To create a custom template

1. Create a template named, for example, 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 for example, /<CATALINA_HOME>/webapps/<contextPath>/templates/simpleTemplate.html. You can put the template anywhere in the webapps folder of a Magnolia instance. 

3. Register the new template in the /config/templatesConfiguration node.
   

4. The new template appears in the dropdown list in the templates messages tool.

Error logging

When you click Send mail in any mail tool a success message "Email successfully sent" or an error message displays 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.

Errors are dealt with sequentially. If there are more than one error, the first error encountered causes the sending failure and this is the message that will appear on the screen. Any further errors are not logged until the initial error is rectified. For example, if you use the testFreemarker template and include the user parameter but not the path parameter, the error message will refer specifically to the path expression in the template.

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

A number of Magnolia modules use the functionality of the Mail module. For more information see:

• Form module
• Public User Registration module
• Observation module
• Workflow