Versions Compared

Old Version 3

changes.mady.by.user Martin Drápela

Saved on

compared with

New Version Current

changes.mady.by.user Christoph Meier

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fix broken anchor links

...

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

...

Javadoc resource link
rangeHigherVersion5.5
classNameinfo.magnolia.module.mail.commands.MailCommand
renderTypeasynchronous
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.

...

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValues

Mgnl f
modules

 

Mgnl f
mail

 


Mgnl f
commands

 

Mgnl f
default

 

Mgnl n
sendMail

 


Mgnl p
class

info.magnolia.module.mail.commands.MailCommand

...

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

...

  • 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.

...

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

Use the first tool to send test mails to verify your Configuring 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.

...

  • 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 .

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValue

Mgnl f
modules

 

Mgnl f
mail

 

Mgnl f
config

 

Mgnl n
simpleConfiguration

 


Mgnl p
body

This is a simple mail.

Mgnl p
from

test@example.com

Mgnl p
subject

 This 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.

...

  • 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 are configured in /modules/mail/config/templateConfiguration . The testFreemarker template is provided as an example.

...

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValue

Mgnl f
config

 


Mgnl f
templatesConfiguration

 

Mgnl n
testFreemarker

 

Mgnl n
attachments

 

Mgnl n
parameters

 


Mgnl p
contentType

html

Mgnl p
from

testfreemarker@example.com

Mgnl p
subject

 This This is a test email for freemarker template

Mgnl p
templateFile

 testFreemarkertestFreemarker.html

Mgnl p
type

freemarker

Mgnl n
pageCommentsNotification

 


Properties:

templatesConfiguration

required

Templates configuration node.

<template name>

required

Template name.

attachments

optional

Javadoc resource link
rangeHigherVersion5.5
classNameinfo.magnolia.module.mail.templates.MailAttachment
renderTypeasynchronous
 provides 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.

...

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValue

Mgnl f
config

 

Mgnl n
factory

 


Mgnl n
renderers

 


Mgnl p
freemarker

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

Mgnl p
magnolia

 infoinfo.magnolia.module.mail.templates.impl.MgnlPageEmail

Mgnl p
simple

 infoinfo.magnolia.module.mail.templates.impl.SimpleEmail

Mgnl p
class

 infoinfo.magnolia.module.mail.MgnlMailFactory

...

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.

...

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:

...

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.

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValue

Mgnl n
testFreemarker

 


Mgnl n
attachments

 

Mgnl n
0001

 

Mgnl p
cid

img

Mgnl p
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

Javadoc resource link
rangeHigherVersion5.5
classNameinfo.magnolia.module.mail.templates.MgnlMultipartEmail
renderTypeasynchronous
 :

Advanced Tables - Table Plus
enableHeadingAttributesfalse
enableSortingfalse
classm5-configuration-tree
enableHighlightingfalse
Node nameValue

Mgnl n
<template configuration>

 

Mgnl n
attachments

 

Mgnl n
<attachment name>

 

Mgnl p
mimeMultipart

mixed

Mgnl p
url

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

Mgnl n
<attachment name>

 


Mgnl p
mimeMultipart

related

Mgnl p
url

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

...

<attachment name>

optional

Attachment name.

mimeMulitpart

optional, default is related

Defines the structure of a 

Javadoc resource link
rangeHigherVersion5.5
classNameinfo.magnolia.module.mail.templates.MgnlMultipartEmail
renderTypeasynchronous
.

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

...

  1. Create a template named, for example simpleTemplate.html using Freemarker code.

    Code Block
    <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.

    Advanced Tables - Table Plus
    enableHeadingAttributesfalse
    enableSortingfalse
    classm5-configuration-tree
    enableHighlightingfalse
    Node nameValue

    Mgnl f
    config

     


    Mgnl f
    templatesConfiguration

     


    Mgnl n
    newUserRegistration

     


    Mgnl n
    attachments

     


    Mgnl n
    parameters

     


    Mgnl p
    contentType

    		html

    Mgnl p
    from

    		info@registrations.com

    Mgnl p
    subject

    		New User Registration

    Mgnl p
    templateFile

    		templates/simpleTemplate.html

    Mgnl p
    type

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

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.