Mail

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

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.

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.

Configuring SMTP

The default transfer protocol (SMTP) settings are configured in /modules/mail/config/smtpConfiguration. These settings are displayed in the Mail subapp.

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

Using client credentials grant flow to authenticate SMTP connections

This section outlines the key configuration steps for Magnolia to access mailboxes in Microsoft Exchange. The client credentials grant flow is used to obtain access tokens over SMTP. These tokens enable secure, application-level access to email without requiring user interaction for authentication. For more information, see the Microsoft legacy protocols documentation.

To configure Microsoft Exchange for Magnolia:

  1. In the Azure portal, grant your Microsoft Entra application the necessary SMTP.SendAsApp permission.

  2. Get tenant admin consent for Magnolia.

    This can be done via an authorization request URL (for multi-tenant applications) or directly through the Microsoft Entra admin center (for single-tenant applications).

  3. Register service principals in Exchange: Use the New-ServicePrincipal cmdlet in Exchange Online PowerShell to register your Entra application’s service principal within Exchange.

  4. Grant mailbox permissions.

    Use the Add-MailboxPermission cmdlet to specify which mailboxes your application’s service principal can access.

  5. Access mailboxes in the Mail module.

    Your Microsoft Entra application can now access the configured mailboxes over SMTP with the OAuth 2.0 client credentials grant flow. Ensure that you use https://outlook.office365.com/.default in the scope property for the access token request.

Configuration using the Mail subapp

The Mail module installs the Mail Tools app. Access to the app is restricted to the superuser role in the app configuration and app launcher layout.

Fields that contain sensitive data, such as passwords, should be managed using the Passwords app.

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

  • SMTP server (the name of your mail server)

  • SMTP port (based on your security settings)

  • Authentication

    • No authentication required

    • Authentication with:

      • Username and password

      • Google OAuth 2.0

      • Microsoft OAuth 2.0

      • Username

      • Password

      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 https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent.

      7. In the Access Token URL field, enter https://oauth2.googleapis.com/token.

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

      9. In the Scope field, enter https://mail.google.com/.

      10. Click the Get New Access Token button.

        OAuth2 settings

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

      • User

      • Tenant ID

      • Client ID

      • Client Secret

  • Connection security method

    • No encryption

    • Use SSL

    • Use STARTTLS

Configuration using definition decoration

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.

Username and password decoration example
smtpConfiguration:
  port: 465
  security: ssl
  server: smtp.gmail.com
  authentication:
    class: info.magnolia.module.mail.smtp.authentication.UsernamePasswordSmtpAuthentication
    passwordKeyStoreId: uuid-of-password-in-password-app-stored-in-keystore-workspace
    user: email@example.com
A decoration file for Google SMTP with OAuth
smtpConfiguration:
  port: 465
  security: tls
  server: smtp.gmail.com
  authentication:
    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
    user: email@example.com
A decoration file for Microsoft SMTP with OAuth
smtpConfiguration:
  port: 587
  security: tls
  server: smtp.office365.com
  authentication:
    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
    user: email@example.com

To get the UUID of an item in the Passwords app:

  1. Open the JCR app.

  2. Choose the keystore workspace.

  3. Click on the filter icon.

    This opens up a checkbox: Display system properties.

  4. Select it, and you can see system properties in the JCR tree, including jcr:uuid ones.

SSL protocol version

You can use the optional sslProtocols property (not displayed in the Mail app) 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 the setup

Using the Mail app

The Verify setup subapp of the Mail app provides tools to:

Verify the current mail settings

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:

  1. Access the relevant profile, typically superuser, in the Security app.

  2. Go to System users and add your email address in the superuser profile.

  3. Set the from address on the template in /modules/mail/config/templatesConfiguration/simpleConfiguration.

  4. Select either plain text or rich text mail type.

  5. Optionally, select an asset attachment from Assets chooser.

  6. Click Send test mail.

Verify 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 the mail settings, the tool sends the test mail to the email address configured in your user profile.

To send a test message:

  1. Select a template in the dropdown. Only registered templates are available. See Templates configuration for more information.

  2. Enter the test data. The content depends on the template configuration.

  3. Click Send test mail.

Using the Groovy app

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

Add the following script to test your setup, adjust the sender and recipient values, and click the Run button to send the test mail.

// Email
sender = "your-sender-mail@test.com"
recipient = "your-receiver-mail@test.com"

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

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

println "Sending mail.... "
mailFactory.getEmailHandler().sendMail(email)

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.

Templates configuration

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

The info.magnolia.module.mail.MailTemplate allows for a number of configuration nodes and properties.

Property Description

templatesConfiguration

required

Templates configuration node.

     <template name>

required

Template name.

         attachments

optional

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

         parameters

optional

Any parameters to be passed to the script.

Do not use parameter names type, contentType.

             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.

Properties Description

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.

  • The url property sets the image location.

Node name Value

⸬ 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 info.magnolia.module.mail.templates.MgnlMultipartEmail:

Node name Value

⸬ <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
Property Description

<attachment name>

optional

Attachment name.

     mimeMulitpart

optional, default is `related`

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

Values:

  • mixed: Standard email attachment.

  • related: Attachment shown inline.

MailAttachment doesn’t use Content-ID properties but uses attachment names (not filenames).

Custom templates

To create a custom template:

  1. In your light module, create a FreeMarker template script named for example simpleTemplate.html.

    <your-light-module>/templates/simpleTemplate.html
    <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. Register the new template in the /mail/config/templatesConfiguration by decorating the Mail module configuration.

    Node name Value

    📁 config

         📁 templatesConfiguration

             ⸬ newUserRegistration

                 ⸬ attachments

                 ⸬ parameters

                 ⬩ contentType

    html

                 ⬩ from

    info@registrations.com

                 ⬩ subject

    New User Registration

                 ⬩ templateFile

    <your-light-module>/templates/simpleTemplate.html

                 ⬩ type

    freemarker

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
Feedback

DX Core

×

Location

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