Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

Magnolia Newsletter module connects Magnolia to an external newsletter service like Campaign Monitor. You can create your newsletter pages in the STK and import them into the external service.

The module provides an API to connect to the external service and a default configuration for Campaign Monitor is included. You can add API keys directly in the module configuration, and create subscribe and unsubscribe forms. The email addresses collected on your site are automatically transferred to the email lists maintained at the external service.

The Newsletter module relies on the Form module to create the necessary forms. Newsletter pages can have a different CSS or even a completely different content structure using Magnolia's sub-template mechanism. Magnolia International uses the Newsletter module to send their newsletter. Compare Magnolia's newsletter on the web with the version used to send the actual newsletter.


The Newsletter module is not bundled with Magnolia and need to be downloaded and installed separately.You can download it from our Nexus repository


Newsletter is a Enterprise Edition module. It is typically not installed. Launch the Configuration app and go to /modules/newsletter, /newsletter-campaign-monitor and /newsletter-stk to check.

 Click for installation steps...

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.


 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.


The module adds three sub modules in /modules:

  • newsletter: Interface to be implemented for your external emailing service. For Campaign Monitor the required nodes are:
    • apiKey: Generated by Campaign Monitor.
    • class: Class that implements the service. HttpSubscriber (Git) is the SubcriberService implementation for HTTP-GET protocol
    • clientId: Generated by Campaign Monitor.
    • defaultListId: Generated by Campaign Monitor.

For more information see Campaign Monitor - API Documentation.

  • newsletter-campaign-monitor: Implements the Newsletter module API for use with your Campaign Monitor account and requires no configuration.

Node name

























The Newsletter STK module includes two custom form components that allow users to subscribe and unsubscribe from mailing lists managed in Campaign Monitor. As newsletters are required to contain an unsubscribe link, the unsubscription component is of less relevance. You can view the components on the demo-features/modules/newsletter page.

Component definitions

The stkNewsletterSubscribe and stkNewsletterUnSubscribe components are configured at /modules/newsletter-stk/templates/components.The components extend the Form component and override the standard form processors. Two custom form processors are provided:

  • SubscribeFormProcessor (Git): Uses the Newsletter module API to perform a subscribe action. Form fields with specific names are expected:
    • email: Mandatory field for a valid email address.
    • displayName: Optional field for a user nickname.
  • UnsubscribeFormProcessor (Git): Uses the Newsletter module API to perform an unsubscribe action. Form field with a specific name isexpected:
    • email: Mandatory field for a valid email address.

Here's the definition for the stkNewsletterSubscribe component.

Node name





































The dialogs referenced by the newsletter component definitions are configured at /modules/newsletter-stk/dialogs/stkNewsletterSubscribe and /stkNewsletterUnSubscribe. The dialogs are identical and contain three tabs:

  • tabMain: A standard Form tab. See Configuring form settings for more information.
  • tabSubmit: A standard Submit settings tab. See Configuring form settings for more information.
  • tabCM: Contains the listId field that provides a dropdown of subscription lists set up in Campaign Monitor. This field uses a uses a custom field definition class, NewsletterSelectorDefinition (Git), that extends the Select field definition, and gets the Campaign Monitor subscription lists.

Node name




































Here's the stkNewsletterSubscribe dialog.

Making components available

The Newsletter STK module makes the newsletter components available in content area in the stkSection template at STK > Template Definitions /pages/stkSection/areas/main/areas/content/availableComponents. You can make the components available on any STK template.

Node name