User Tools

Site Tools


OpenEMM Install & Configuration Wiki

Latest Version of OpenEMM 19.10: Backend:, Frontend:
Latest Version of OpenEMM 20.04: Backend:, Frontend:
Latest Version of OpenEMM 20.10 BETA:
Utility Package for OpenEMM Deployment & Runtime: 20.04.049 (OpenEMM 20.04) or 20.10.031 (OpenEMM 20.10)
(as of October 1, 2020)

This wiki provides the brief version of the extensive OpenEMM Installation & Administration Guide 1.2.0 (including SLES instructions) for OpenEMM 19.10.

The lastest runtime version offers you to upgrade to OpenEMM 20.10 BETA. Because several things have changed in OpenEMM version 20.04 and later, we created a Installation & Administration Guide for OpenEMM 20.04 and a brand-new OpenEMM 20.10 Installation & Administration Guide 1.0.2. For OpenEMM 20.04 and 20.10, please use the PDF guides instead of this wiki.

We kindly ask you to contribute your feedback and questions to improve the documentation, installation, configuration and administration of OpenEMM! Please leave your questions and comments in the OpenEMM forum at

1. Introduction

OpenEMM is a professional open source software for email marketing and automation. If you want to automate your email communication, OpenEMM is the right choice for you.
The first version of OpenEMM was published in 2006. The source code of the frontend and the backend of OpenEMM 19.04 and later is available at GitHub. It uses the popular open source license AGLPv3. At the end of this page you can find instructions on how to build OpenEMM by yourself.

2. Requirements

  • RedHat 7 or 8; CentOS 7 or 8; SLES 15 (OpenEMM 19.10 and later)
  • Java Open JDK 8 (any OpenEMM) or Java Open JDK 11 (OpenEMM 20.04)
  • Apache Tomcat 9
  • Python 2.7 (OpenEMM 19.x) or Python 3.8 (OpenEMM 20.04)
  • DBMS: MariaDB 10.1, 10.2 or 10.3; MySQL 5.6 or 5.7
  • MTA: Postfix 2.6 or later; Sendmail 8.10 or later
  • wkhtmltox or later
  • for HTTPS support: Apache Tomcat Native Library

If you want to install or upgrade to OpenEMM 20.04, please use the PDF guide mentioned above.

3. Preparations for 19.10

OpenEMM consists of 2 packages:

  1. backend code for generation and dispatch of emails, management of bounces and replies: openemm-backend-19.*.000.*.tar.gz
  2. frontend code with GUI, statistics service (charts & diagrams) and webservices: openemm-frontend-19.*.000.*.tar.gz

We also offer a utility package for easy deployment and operations of the binary code of OpenEMM: openemm-runtime-19.*.tar.gz

Unless noted otherwise below, use user “root”.

The following instructions in this chapter are targeted at RedHat 7 or CentOS 7. Beginning with OpenEMM 19.10, linux distribution SLES 15 is supported as well. In this case, please follow the instructions here.

3.1 Packages of Operating System

Install the required packages:

# yum install gcc
# yum install python
# yum install java-1.8.0-openjdk-devel
# yum install xorg-x11-fonts-75dpi zlib fontconfig freetype libX11 libXext libXrender urw-fonts

3.2 DBMS

Depending on the DBMS you want to use, either install MariaDB or MySQL.

MariaDB and MySQL code repository for RedHat7:

# subscription-manager repos –enable rhel-server-rhscl-7-rpms

MariaDB and MySQL code repository for CentOS7:

# yum install centos-release-scl

Tip: After installation of either MariaDB or MySQL, you should consider running script mysql_secure_installation to set a password for user root, to remove any anonymous users and to disallow remote logins.


This example uses MariaDB 10.2:

# yum install rh-mariadb102-mariadb-server
# yum install MySQL-python

Make sure MariaDB is running and re-started at every server reboot:

# systemctl enable rh-mariadb102-mariadb
# systemctl start rh-mariadb102-mariadb

Finally, set a symlink to make sure that OpenEMM can find MariaDB:

# cd /bin
# ln -s /opt/rh/rh-mariadb102/root/bin/* .


This example uses MySQL 5.7:

# yum install rh-mysql57-mysql-server
# yum install MySQL-python

Make sure MySQL is running and re-started at every server reboot:

# systemctl enable rh-mysql57-mysql
# systemctl start rh-mysql57-mysql

Finally, set a symlink to make sure that OpenEMM can find MySQL:

# cd /bin
# ln -s /opt/rh/rh-mysql57/root/bin/* .

3.3 MTA

Depending on the MTA you want to use, either install Sendmail or Postfix.

MTA Sendmail

If you want to use Sendmail as SMTP server (MTA), you have to stop and remove Postfix first (in case it is installed), and you have to install the required packages for Sendmail.

# systemctl stop postfix
# yum remove postfix
# yum install sendmail sendmail-cf sendmail-milter procmail

After that, if necessary, switch the default SMTP server to Sendmail with

# alternatives --set mta /usr/sbin/sendmail.sendmail

and change Sendmail's configuration: Open file in directory /etc/mail and add a leading “dnl ” to line

DAEMON_OPTIONS(`Port=smtp,Addr=, Name=MTA')dnl

This will enable Sendmail to listen on all available network interfaces and allows the processing of asynchronous bounces and auto responder mails. By default, Sendmail listens only on the local interface for connections, but dnl comments out this directive.

Additionally, add line

INPUT_MAIL_FILTER(`bav', `S=unix:/home/openemm/var/run/bav.sock, F=T')dnl

at the end of file to make Sendmail familiar with OpenEMM's mail filter BAV (bounce address validator) so that the bounce management can process asynchronous bounces, too.
The mailloop service of OpenEMM, which processes the asynchronous bounces and auto responder mails needs some more preparations:

# cd /etc/mail
# umask 022
# [ -f relay-domains ] || touch relay-domains
# [ -f mailertable ] || touch mailertable

To activate your changes to the Sendmail configuration you have to compile the intermediate file to the final configuration file and activate the new configuration with

# cd /etc/mail
# make
# systemctl restart sendmail

MTA Postfix

If you want to use Postfix as SMTP server (MTA), you have to stop and remove Sendmail first (in case it is installed), and you have to install the required packages for Postfix.

# systemctl stop sendmail
# yum remove sendmail
# yum install postfix sendmail-milter procmail

After that, switch the default SMTP server to Postfix with

# alternatives --set mta /usr/sbin/sendmail.postfix

and change Postfix' configuration to unleash all features. To do this, change to the Postfix main configuration directory:

# cd /etc/postfix

and add some configuration parameters to Postfix' main configuration file

inet_interfaces = all
inet_protocols = all
mailbox_command = /usr/bin/procmail
mailbox_size_limit = 0
message_size_limit = 0
maximal_queue_lifetime = 1d
bounce_queue_lifetime = 1d
smtp_tls_security_level = may
smtp_tls_protocols = !SSLv2, !SSLv3
smtp_tls_ciphers = high
smtp_tls_mandatory_ciphers = $smtp_tls_ciphers
hash_queue_depth = 2
enable_long_queue_ids = yes
relay_domains = /home/openemm/var/run/
transport_maps = hash:/home/openemm/var/run/transport.maps
smtpd_milters = unix:/home/openemm/var/run/bav.sock

If lines with parameters of the same name already exist in file, comment them with character # at the beginning to avoid any warning messages or overwrite them with the new values in case you do not want to keep the original values as backup.
Additionally, you have to set parameter myhostname in file to the FQDN of your OpenEMM server. Otherwise, mails would be sent with sender domain localhost.localdomain instead.

Finally, add these lines to configuration file

mailloop  unix  -       n       n       -       -       pipe
  flags=RX user=openemm argv=/usr/bin/procmail /home/openemm/lib/bav.rc

Please do not omit the two space characters before keyword “flags” to indicate the parser that the line is continued!
Last not least, activate the TLS manager in file by uncommenting (i.e. removing the leading #) line

tlsmgr unix - - n 1000? 1 tlsmgr

to permit sending of TLS encrypted emails.
To activate your changes, restart Postfix with

# systemctl restart postfix

3.4 wkhtmltox

Download the RPM of “wkhtmltox” from and unpack it:

# rpm -ihv wkhtmltox-*.rpm

3.5 Firewall

Open port 25 and port 8080 in the firewall and add a port forwarding from port 80 to 8080, so you do not have to enter the URL of your OpenEMM server with “:8080” at the end:

# firewall-cmd --get-active-zones

If your zone is “public” (if not, use the zone name you got with the aforementioned statement):

# firewall-cmd --zone=public --add-port=8080/tcp --permanent
# firewall-cmd --zone=public --add-port=25/tcp --permanent
# firewall-cmd --zone=public --add-forward-port=port=80:proto=tcp:toport=8080 --permanent
# firewall-cmd --reload

4. Installation for 19.10

4.1 Group and User

Create group and user for OpenEMM:

# groupadd openemm
# useradd -m -g openemm -d /home/openemm -s /bin/bash openemm
# passwd openemm
# su - openemm

4.2 OpenEMM Download

We recommend to download the latest deployment & runtime package of OpenEMM from here. This package provides the installer for the backend and frontend code. Of course, you can also take the source code of OpenEMM from GitHub and compile and deploy the software manually yourself. See the instructions at the end of this page.

4.3 Runtime Deployment

Download runtime tarball (file name: openemm-runtime-19.*.tar.gz) to /home/openemm to create the deployment and runtime environment for OpenEMM.

Change to user openemm, unpack and start it with

# su - openemm
$ tar -xvzpf openemm-runtime-19.*.tar.gz
$ ./

Due to bug in Runtime versions before 19.07.015 a symlink was missing after instalation (it is only created after the first update of the runtime package). Create this symlink with

$ ln -s /home/openemm/tomcat/bin/ /home/openemm/bin/

This symlink makes sure that the backend is restarted, too, when restarting OpenEMM.

At launch time OpenEMMInstaller checks your environment and offers to install required packages (including Tomcat 9), to configure a database connection (file dbcfg) and to set environment variables

  • JAVA_HOME (default: /usr/lib/jvm/java) for Java
  • CATALINA_HOME (default: /home/openemm/opt/tomcat/) for Tomcat
  • WKHTML (default: /usr/bin/wkhtmltoimage) for tool wkhtmltox

The parameters will be written to file in directory /home/openemm/bin/.

OpenEMMInstaller also checks if kernel parameter in /etc/security/limits.conf are sufficient and, if not, offers to change them. However, you have to restart OpenEMMInstaller as user root to be able to change the file:

$ sudo su -
# /home/openemm/bin/

If database configuration file dbcfg does not exist in directory /home/openemm/etc/, OpenEMMInstaller asks for the required parameters like database type (“mysql” or “mariadb”), database name (“openemm”), database user (“openemm”) and your database password.

4.4 Frontend and Backend Deployment

For the deployment of the backend tarball you have to run OpenEMMInstaller as user root, because some files of the tarball have to be deployed with root permissions:

$ sudo su -
# /home/openemm/bin/

Use menu “Install or update package from AGNITAS website” to install the frontend and backend package. The same menu also offers to install Tomcat or an update of the runtime package, but you can select “n” for any package, if you do not want to install or update it.
During Deployment of the backend tarball several new directories and symlinks will be created in /home/openemm/.

If you do not want to install the backend package of OpenEMM, you can start OpenEMMInstaller as user “openemm”:

# su - openemm

When the frontend is installed, the OpenEMM database is automatically filled with its initial content.

5. Configuration for 19.10

5.1 Log Access

OpenEMM requires read access to the mail log file at /var/log/maillog and logrotate has to be aware of this fact, too. Open file /etc/logrotate.d/syslog and add the following line after the line sharedscripts:

# create 0644

and run

# chmod 644 /var/log/maillog

to set the permissions of the current maillog.

5.2 OpenEMMInstaller

Use menu “Configuration and “Security” of OpenEMMInstaller to set up and change the configuration of OpenEMM.

Set various essential parameters in sub-menu “Change” of menu “Configuration”:

Use menu “Configuration”, sub-menu “Change client/account data in db” to set important values in the OpenEMM database:

  • Set rdir_domain to the protocol and FQDN of your OpenEMM server, for example This domain will be used in all measureable links to redirect them through OpenEMM.
  • Set mailloop_domain to the domain of your sender address. The domain for the mailloop service must be different from the name of your OpenEMM server. It usually is the FQDN which is defined in the MX record for your server, for example, pointing as MX to In this case, use domain as domain for the sender address of your mailings. (There are other ways for configuration, described in the OpenEMM Install&Admin Guide.) If you do not configure the mailloop service, OpenEMM can only process instant bounces, i.e. you will not be able to catch all bounces (see section Mailloop Configuration below).

Finally, create an initial password for main user “emm-master” in menu “Security”. Write down the generated password and use user “emm-master” and this initial password later for your first login. At first login, you will be prompted to change your password to a new one of your choice.

Launch OpenEMM with menu “Restart OpenEMM”. Experts may have a look at the Tomcat log during startup with

$ tail -f logs/catalina.out

to check for any warnings or error messages.

Point your browser to your OpenEMM server and log in with user “emm-master” and the password you just created. OpenEMM will ask you to change the initial password to a new one of your choice.

If you want to install the context-sensitive help feature of OpenEMM, download it via OpenEMMInstaller menu “Install or update package from AGNITAS Website” (not available, yet).

5.3 Templates and Forms

You do not have to start from scratch when producing mailings and creating forms in OpenEMM. At you can download templates and forms which you can import into OpenEMM. Make sure to replace all placeholders for a company ID with value “1”.

5.4 Mailloop Configuration

The mailloop service of OpenEMM pocesses asynchronous bounces, i.e. bounces that are not sent back instantly by the receiving MTA, but only after a delay. There are several options to configure the mailloop service. See section OpenEMM Mailloop Configuration for details.

6. Updates

The top of this Wiki lists the latest available versions of OpenEMM backend, frontend and the deployment & runtime package.

You can download the latest versions of packages with menu “Install or update package from AGNITAS Website” of OpenEMMInstaller. An update of the frontend package will also update the schema of the OpenEMM database, if necessary. Please keep in mind that you have to start OpenEMMInstaller as user root, if you want to update the backend, too.

If you use runtime version or later, you are offered to upgrade to new release OpenEMM 20.04. If you are not happy with the new release (or any other version of OpenEMM), you can roll back OpenEMM to an earlier (or later) version with menu “Switch OpenEMM version”.

Do not forget to restart OpenEMM with menu “Restart OpenEMM” after you have downloaded and installed an update package to activate it. But do the restart at an convenient time: Do not restart OpenEMM during a dispatch of a mailing, or right after the dispatch (due to the brief downtime of the redirect service causing missed openings and click redirects).

7. Administration

7.1 Ressources

The beta PDF version of the user manual for OpenEMM 2019 is now available at

Here is a video with first steps:

7.2 Automated Startup

If you want OpenEMM to automatically launch at server reboot, you can use a systemd unit file for that purpose. Create a new file openemm.service in directory /etc/systemd/system/ with the following content:

Description=OpenEMM startup script
After=var-run.mount sendmail.service postfix.service

ExecStart=/home/openemm/bin/ start
ExecStop=/home/openemm/bin/ stop


After deploying this file, reload the systemd-daemon and enable the openemm service with

# systemctl daemon-reload
# systemctl enable openemm

At next server reboot, OpenEMM will be started automatically.

8. Known Issues

8.1 Open Issues

  • O-409: openings and clicks are always shown for end user device class “PC” independent from its real origin

8.2 Fixed Issues

Frontend or later:

  • E-7052: no limit for no. of recipient profile fields

Frontend or later:

  • O-447: statistics for mailing comparision do not work

Frontend or later:

  • O-416: database update script reports error due to missing database entry

Frontend or later:

  • O-400: Export wizard does not allow change of character set

Frontend or later:

  • E-7031: Login does not work with IPv6 addresses

Backend or later:

  • O-465: binary backend now works with both CentOS 8 and 7 out of the box

Backend or later:

  • L-511: during busy times process table is not cleaned up properly from defunct python processes

Runtime or later:

  • O-404: OpenEMMInstaller uses incorrect path for Tomcat Native (TLS support)

Runtime or later:

  • O-403: Tomcat updates by the OpenEMMInstaller could overwrite individual configuration (like TLS settings)

Runtime or later:

  • O-401: In some cases the OpenEMMInstaller did not launch when installed for the very first time

Runtime or later:

  • O-396: In some cases the OpenEMMInstaller can not create the initial database for OpenEMM

Runtime 19.07.015 or later:

  • O-365: deploy & runtime package creates symlink to in /home/openemm/bin only after update

Runtime 19.07.011 or later:

  • simplified update process with “ -update”

Runtime 19.07.005 or later:

  • O-281: menu 4 of OpenEMMInstaller also offers to update deployment & runtime package

Runtime 19.07.004 or later:

  • O-358: menu “Show OpenEMM status” of OpenEMMInstaller shows status of backend

Manual 20.04.010 or later:

  • O-291: content for help menu is not available yet for download

9. New Features of OpenEMM 19.10 (major changes)

  • E-6653: (reminder) campaigns can be sent to recipients with status “waiting for confirmation”
  • E-6587: improved filtering of invalid form data
  • E-6553: profile field cleaning for recipients without active binding after 30 days (data minimization)
  • E-6390: add bcc option for optional email archive to date triggered mailings
  • E-6292: if a search for an email address does not produce a hit, offer to create a new recipient with this address
  • E-6249: improved usability for visual target group editor
  • E-5438: email header “List-Unsubscribe” supports RFC 8058 for one-click unsubscriptions
  • O-0363: make OpenEMM work with Suse Linux 15
  • G-4051: context-sensitive auto-complete suggestions for EQL editor
  • B-0849: new field entry_mailing_id in customer_binding_tbl for mailing that caused opt-in
  • B-0844: new link hash tag for encyption of data field
  • various minor usability improvements like easier navigation, better formatting and sorting, optimized default settings, more precise notifications, better warning and error messages, new help balloons, additional logging of user activities, etc.

10. New Features of OpenEMM 20.04 (major changes)

  • E-7114: new methods getMailingName and getMailingSubject for use in Velocity scripts
  • E-7053: edit mode for comments in blacklist records
  • E-7022: warning when saving a mailing with obsolete tags
  • E-6956: prevent disabling of mailings used in activated autoresponder
  • E-6955: new field “reason” for blacklist entries
  • E-6954: action-based mailings used by bounce filters can not be deactivated
  • E-6947: show relations of custom profile fields to target groups
  • E-6934: show fields of default salutations as read-only
  • E-6905: show by which actions an action-based mailings is used
  • E-6901: keep search parameters for multiple recipient searches
  • E-6883: bulk delete feature for images
  • E-6841: improved usability for creating date-based target groups
  • E-6824: “used in” tab of target groups extended with mailing content blocks and export profiles as “used in” sources
  • E-6762: improved usability for page to edit mailing contents
  • E-6526: improved usability for HTML-to-text conversion option
  • E-6468: redesign of configuration page in tab “send mailing”
  • E-6431: email confirmation for password changes
  • E-6329: improved usability of configuration for bounce filter and autoresponder
  • E-5987: edit lock for mailing content if more than one user tries to change it at the same time
  • E-5839: when a newly entered email address already exist, offer to show (and edit) its profile data
  • E-5586: new permission for every web service method to grant fine-grained permission schemas to web service accounts
  • E-5583: new math tag agnDAYS_UNTIL
  • E-5496: show anonymous openings and clicks over time in separate charts
  • E-5223: detect duplicate recipients in EMM database
  • E-4686: brute-force login protection for webservices API
  • E-4542: end device type as selector for heatmap statistics
  • E-2609: assess complexity of target groups and show resulting performance indicators
  • E-0707: redesign of left navigation bar
  • G-4289: reworked link tab for user forms
  • G-4376: A/B test campaigns for workflow manager and new tab “Auto Optimization” in sub-menu Archive of Mailing menu
  • S-1791: ability to stop and resume mailings even when generation or sending of mailing has already started
  • various minor usability improvements like easier navigation, better formatting and sorting, optimized default settings, more precise notifications, better warning and error messages, new help balloons, additional logging of user activities, etc.

11. New features of OpenEMM 20.10 (major changes)

  • E-7664: User roles can be assigned to another user role
  • E-7639: support more than one forward email address for response mail filters
  • E-7518: more granular data types: for numbers integer and float can be selected, for dates datetime and date only are possible
  • E-7438: univeral RESTful API
  • E-7396: new script methods for subscription forms to filter accepted and rejected email address domains
  • E-7105: period of validity for passwords and 2FA cookies can be configured via GUI
  • E-7103: number of login retries and blocking time can be configured via GUI
  • E-7101: revised requirements for complexity of GUI passwords and WS passwords (can be modified by user)
  • E-7084: sort option for link list in link tab of mailing menu
  • E-6793: OpenEMM users can be assigned more than one role
  • E-6529: statistic summary for auto-optimized list split mailings
  • E-6294: allow date calculations for target groups using binding information
  • E-0712: dark mode for GUI
  • G-4162: export of web forms as JSON file
  • G-4157: export of mailings as JSON file
  • L-0483: extend system status page with download of individual configuration parameters (backup)
  • O-0417: backend and frontend merged into one single tarball
  • various minor usability improvements like easier navigation, better formatting and sorting, optimized default settings, more precise notifications, better warning and error messages, new help balloons, additional logging of user activities, etc.

12. Building OpenEMM yourself

Download the source code of OpenEMM from GitHub at to a directory of your choice.


$ sudo su -
# cd backend
# ./


Copy template files, and to files with names, and and adapt the paths listed in those three files to your needs.

$ cd frontend
$ ant -f build.xml
start.txt · Last modified: 2020/10/18 10:02 by ma