Page tree
Skip to end of metadata
Go to start of metadata

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.

Configuration

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

Node name

 modules

 mail

 apps

 fieldTypes

 config

 commands

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 the Mail tools app before automating the process for production use.

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

Node nameValues

 modules

 

 mail

 

 commands

 

 default

 

 sendMail

 

 class

info.magnolia.module.mail.commands.MailCommand

Configuring SMTP

The Mail module installs the Mail Tools app that is accessible in Tools > Mail tools. The app is based on the small app concept. Permission to access the app is limited to the superuser role in both the app configuration and the app launcher layout.

The default transfer protocol (SMTP) settings are configured at Configuration > /modules/mail/config/smtp. These setting display the Mail subapp.

Add your SMTP settings in the Mail supapp to update the smtp configuration node:

  • SMTP server: Name of your mail server.
  • Authentication: Select:
    • Authentication with username and password,
      • Username: SMTP user name.
      • Password: SMTP user's password.
    • No authentication required.
  • Security:
    • No encryption for simple SMTP (default communication port is 25).
    • SMTP over SLL (SMTPS, SSL v3) (port 465).
    • (port 587).
  • Port: Dependent on security setting.

Verifying setup

The Verify setup subapp provides tools to:

  1. Verify the current setup.
  2. Verify message templates.

Use the first tool to send test mails to verify your SMTP settings. The tool sends a pre-configured simple mail with an optional attachment to the email address in the logged in user's profile.

To send a test message:

  • Access the relevant profile, typically superuser, in the Security app. Go to System users and add your email address in the superuser profile.
  • Select either plain text or rich text mail type.
  • Optionally, select an asset attachments from the DAM in the Assets chooser
  • Click Send Test Mail.

The content of the test mail is configured in /modules/mail/config/simpleConfiguration.

Node nameValue

 modules

 

 mail

 

 config

 

 simpleConfiguration

 

 body

This is a simple mail.

 from

test@example.com

 subject

 This is a test mail.

Message templates

The second tool in the Verify setup subapp allows you to verify your mail message templates. Message templates are typically used by forms on pages to send the data to the user who submitted the form.

As in the case of verifying mail settings, the tool sends the test mail to the email address configured in your user profile.

To send a test message:

  • Select a template in the dropdown. Only registered templates are available. See Templates configuration for more information.
  • Enter the test data. The content depends on the template configuration.
  • Click Send Test Mail.

Templates configuration

Templates are configured in /modules/mail/config/templateConfiguration. 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:

Node nameValue

 config

 

 templatesConfiguration

 

 testFreemarker

 

 attachments

 

 parameters

 

 contentType

html

 from

testfreemarker@example.com

 subject

 This is a test email for freemarker template

 templateFile

 testFreemarker.html

 type

freemarker

 pageCommentsNotification

 

Properties:

templatesConfiguration

required

Templates configuration node.

<template name>

required

Template name.

attachments

optional

MailAttachment  provides for a number of attachment options.

parameters

optional

Any parameters to be passed to the script.

templateFile

required

Relative path to the template script. 

type

required

Scripting language used in the template.

contentType

optional

Type of content for the message body. It is only necessary to include this property for HTML emails.

from

optional

Email address that will appear in the From field of the message, unless defined elsewhere, for example in Form module.

subject

optional

Subject line of the email, unless defined elsewhere for example in the Form module.

pageCommentsNotification is used by the Commenting module.

Template renderers

Template renderers are registered  in /modules/mail/config/factory/renderers:

Node nameValue

 config

 

 factory

 

 renderers

 

 freemarker

info.magnolia.module.mail.templates.impl.FreemarkerEmail

 magnolia

 info.magnolia.module.mail.templates.impl.MgnlPageEmail

 simple

 info.magnolia.module.mail.templates.impl.SimpleEmail

 class

 info.magnolia.module.mail.MgnlMailFactory


Properties:

renderers

optional

Renderers node.

freemarker

optional

Renders FreeMarker email templates.

magnolia

optional

Renders Magnolia web pages in an email.

simple

optional

Renders simple text emails that do not require a specific scripting language to be parsed.

 

Template script

Here's the example testFreemarker.html 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 verify templates 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.

Node nameValue

 testFreemarker

 

 attachments

 

 0001

 

 cid

img

 url

 http://www.magnolia-cms.com/.imaging/amplify-miami-2014/imageForTeaserBinary/miami.png

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

Node nameValue

 <template configuration>

 

 attachments

 

 <attachment name>

 

 mimeMultipart

mixed

 url

 http://www.magnolia-cms.com/.imaging/amplify-miami-2014/imageForTeaserBinary/miami.png

 <attachment name>

 

 mimeMultipart

related

 url

 http://www.magnolia-cms.com/.imaging/amplify-miami-2014/imageForTeaserBinary/miami.png

Properties:

<attachment name>

optional

Attachment name.

mimeMulitpart

optional, default is related

Defines the structure of a  MgnlMultipartEmail .

Values:

  • mixed: Standard email attachment.
  • related: Attachment shown inline.

MailAttachment does not use Content-ID properties but uses attachment names (not file names).

 


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.

    Node nameValue

     config

     

     templatesConfiguration

     

     newUserRegistration

     

     attachments

     

     parameters

     

     contentType

    html

     from

    info@registrations.com

     subject

    New User Registration

     templateFile

    templates/simpleTemplate.html

     type

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

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.

  • No labels