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.


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

info.magnolia.module.mail.commands.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 name Values

📁 modules

     📁 mail

         📁 commands

             📁 default

                 ⸬ sendMail

                     ⬩ class


Configuring SMTP

The default transfer protocol (SMTP) settings are configured in /modules/mail/config/smtpConfiguration. Add your SMTP settings via decorations on the module’s config file: /mail-config/decorations/mail/config.yaml. Below are some commonly used configuration examples.

For OAuth 2.0-related information, see also these external resources:

Username and password decoration example
  port: 465
  security: ssl
    class: info.magnolia.module.mail.smtp.authentication.UsernamePasswordSmtpAuthentication
    passwordKeyStoreId: uuid-of-password-in-password-app-stored-in-keystore-workspace

To use the Google username/password example decoration below, you must enable Less secure apps.

Decoration file for Google SMTP with OAuth
  port: 465
  security: tls
    class: info.magnolia.module.mail.smtp.authentication.GoogleOauthSmtpAuthentication
    clientId: client-id
    clientSecretKeyStoreId: uuid-of-secret-key-in-password-app-stored-in-keystore-workspace
    refreshTokenKeyStoreId: uuid-of-refresh-token-in-password-app-stored-in-keystore-workspace

Refreshing access tokens for Google OAuth 2.0

The Google OAuth 2.0 authentication type supported by the Mail module leverages OAuth 2.0 Client IDs. This type by default requires user interaction, which doesn’t readily suit the use case of sending emails automatically.

As a workaround for this limitation, you can follow the procedure described in Refreshing an access token (offline access). You can use the Postman to refresh a token.

Click to see the details.

  1. Open the Postman app.

  2. Create a new request.

  3. On the Authorization tab, choose OAuth 2.0 as the authorization type.

  4. In the Grant Type field, select Authorization Code.

  5. In the Callback URL part, check Authorize using browser.

  6. In the Auth URL field, enter

  7. In the Access Token URL field, enter

  8. In the Client ID and Client Secret fields, input your client id and client secret, respectively.

  9. In the Scope field, enter

  10. Click the Get New Access Token button.

OAuth2 settings

After this, the browser opens a form where you can sign in and then refresh the token.

Refresh token

There are other ways of obtaining a refresh token, for example Exchange authorization code for refresh and access tokens.

Development work is underway to support Service Accounts for Google OAuth 2.0 in Magnolia (MGNLMAIL-205, restricted access). This authentication type is designed for server-to-server communication and fits best for the Mail module use case. Its configuration is simpler and without the need to configure a refresh token.
Decoration file for Microsoft SMTP with OAuth
  port: 587
  security: tls
    class: info.magnolia.module.mail.smtp.authentication.MicrosoftOauthSmtpAuthentication
    clientId: client-id
    tenantId: tenant-id
    clientSecret: uuid-of-client-secret-in-password-app-stored-in-keystore-workspace

To get the UUID of an item in the Password app, open the JCR app, choose the keystore workspace, and then click on the filter icon. This opens up a checkbox: Display system properties. Select it, and you can see system properties in the JCR tree, including jcr:uuid ones.

UUID keystore viewer

SSL protocol version

Since version 5.5.13 of the Mail module, you can use the optional sslProtocols property to set the version of the SSL protocol(s) to be used. The property value is a whitespace-separated list of tokens, for example:

sslProtocols: TLSv1.1 TLSv1.2

Verifying setup

You can verify your setup with the Groovy app. In the Groovy app, you should see the sendMail script.

  1. Set the sender and recipient you want

  2. Click the Run button to send the test mail

If your Groovy app doesn’t have the sendMail script, you can add one like the script below to test your setup.

// Email
sender = ""
recipient = ""

mailModule = info.magnolia.objectfactory.Components.getComponent(info.magnolia.module.mail.MailModule)
mailFactory = mailModule.getFactory()

email = mailFactory.getEmail([:], [])
email.setSubject("Test Mail")
email.setBody("Test email from the Groovy console!")

println "Sending mail.... "

println "Done!"

SMTP connection timeout

Using the timeoutInMillis setting on the SMTP configuration will define when a connection attempt to the server times out.

To set connection timeout:

  1. From the Configuration app, find the SMTP configuration node (/modules/mail/config/smtpConfiguration).

  2. Add a timeoutInMillis property and set its value accordingly. The default value is 5000 (milliseconds).

SMTP session debugging

Using the debug setting on the SMTP configuration will enable a dump of the session data to system out.

The session debug is only shown in the standard output and not printed to the log file.

To enable session debugging:

  1. From the Configuration app, find the SMTP configuration node (/modules/mail/config/smtpConfiguration).

  2. Add a debug property and set its value to true.

  3. From the console see the detailed session debug data.

    Click to see a debug data.

    DEBUG: setDebug: JavaMail version 1.6.2
    2020-05-04 18:07:25,329 DEBUG info.magnolia.module.mail.templates.MgnlEmail : Set attachments [0] for mail: [info.magnolia.module.mail.templates.impl.FreemarkerEmail]
    DEBUG: getProvider() returning javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Oracle]
    DEBUG SMTP: need username and password for authentication
    DEBUG SMTP: protocolConnect returning false,, user=magnolia.cms, password=<null>
    DEBUG SMTP: useEhlo true, useAuth true
    DEBUG SMTP: trying to connect to host "", port 465, isSSL true
    220 ESMTP
    DEBUG SMTP: connected to host "", port: 465
    EHLO localhost
    250-SIZE 160000000
    250 DSN
    DEBUG SMTP: Found extension "PIPELINING", arg ""
    DEBUG SMTP: Found extension "SIZE", arg "160000000"
    DEBUG SMTP: Found extension "AUTH", arg "PLAIN LOGIN"
    DEBUG SMTP: Found extension "AUTH=PLAIN", arg "LOGIN"
    DEBUG SMTP: Found extension "ENHANCEDSTATUSCODES", arg ""
    DEBUG SMTP: Found extension "DSN", arg ""
    DEBUG SMTP: protocolConnect login,, user=magnolia.cms, password=<non-null>
    DEBUG SMTP: Attempt to authenticate using mechanisms: LOGIN PLAIN DIGEST-MD5 NTLM XOAUTH2
    DEBUG SMTP: Using mechanism LOGIN
    DEBUG SMTP: AUTH LOGIN command trace suppressed
    DEBUG SMTP: AUTH LOGIN succeeded
    DEBUG SMTP: use8bit false
    MAIL FROM:<>
    250 2.1.0 Ok
    RCPT TO:<>
    250 2.1.5 Ok
    RCPT TO:<>
    250 2.1.5 Ok
    DEBUG SMTP: Verified Addresses
    354 End data with <CR><LF>.<CR><LF>
    Date: Mon, 4 May 2020 18:07:25 +0200 (CEST)
    Message-ID: <1617772963.1.1588608445333@localhost>
    Subject: This is a test email for freemarker template
    MIME-Version: 1.0
    Content-Type: text/html; charset=UTF-8
    Content-Transfer-Encoding: 7bit
    <img src="cid:0001"/>
    This is the path that has been changed:
    250 2.0.0 Ok: queued as CCE8A10036F
    DEBUG SMTP: message successfully delivered to mail server
    221 2.0.0 Bye
    2020-05-04 18:07:26,080 INFO fo.magnolia.module.mail.handlers.SimpleMailHandler: Mail has been sent to: [,]

Templates configuration

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

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

Node name Value

📁 config

     📁 templatesConfiguration

         ⸬ testFreemarker

             ⸬ attachments

             ⸬ parameters

             ⬩ contentType


             ⬩ from

             ⬩ subject

This is a test email for freemarker template

             ⬩ templateFile


             ⬩ type


         ⸬ pageCommentsNotification

Property Description



Templates configuration node.

     <template name>


Template name.



info.magnolia.module.mail.templates.MailAttachment provides for a number of attachment options.



Any parameters to be passed to the script.

Do not use parameter names type, contentType.



Relative path to the template script.



Scripting language used in the template.



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



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



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 name Value

📁 config

     ⸬ factory

         ⸬ renderers

             ⬩ freemarker


             ⬩ magnolia


             ⬩ simple


         ⬩ class


Properties Description



Renderers node.



Renders FreeMarker email templates.



Renders Magnolia web pages in an email.



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.

    <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:



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 name Value

⸬ testFreemarker

     ⸬ attachments

         ⸬ 0001

             ⬩ cid


             ⬩ url

The mimeMultipart property can be used to define the structure of info.magnolia.module.mail.templates.MgnlMultipartEmail:

Node name Value

⸬ <template configuration>

     ⸬ attachments

         ⸬ <attachment name>

             ⬩ mimeMultipart


             ⬩ url

         ⸬ <attachment name>

             ⬩ mimeMultipart


             ⬩ url

Property Description

<attachment name>


Attachment name.


optional, default is `related`

Defines the structure of info.magnolia.module.mail.templates.MgnlMultipartEmail.


  • mixed: Standard email attachment.

  • related: Attachment shown inline.

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

Custom templates

To create a custom template:

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

        <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>
  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 name Value

    📁 config

         📁 templatesConfiguration

             ⸬ newUserRegistration

                 ⸬ attachments

                 ⸬ parameters

                 ⬩ contentType


                 ⬩ from

                 ⬩ subject

    New User Registration

                 ⬩ templateFile


                 ⬩ type


  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.

Related topics

DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.