OpenEMM User SelfserviceFree support for OpenEMM
This website offers a wealth of free of charge support services and information for all users of OpenEMM. Since OpenEMM is open source, free support is provided as selfservice only. Here you can find a lot of tips how you can help yourself!
If you are interested in commercial services like setup support, a service contract, hosting and administration or development, please have a look at the list of Commercial Services for OpenEMM. Please understand that we cannot offer unpaid consulting for OpenEMM and can only accept projects from half a man-day (4 hours | 150 € per hour).
OpenEMM forumFree support from the OpenEMM community
The OpenEMM forums offer interactive support from the OpenEMM user community. Every now and then the developers of OpenEMM take part, too. Topics and posts are sorted by category – from installation & Upgrades over usage, bounce management, extensions, development, bug fixing, suggestions, miscellaneous up to usability. Most likely, your topic has already been discussed in one of several hundreds of posts. Unless be the first one and ask the OpenEMM community…
Tutorials & VideosGet up to speed quickly with OpenEMM
First steps in OpenEMM
Here is an overview of the steps required after installation in OpenEMM (video based on version 2019 and later).
Further tutorials on how to use the software can be found in our YouTube Channel.
Ressources for downloadDocumentation, source code files, extensions and more
The download center offers various support documents and manuals on OpenEMM (up to version 2015 R2) for free. Additional resources such as the user manual and free templates for OpenEMM 2019 (and higher) can be found in the Download Center.
Install guides, documentation, manuals and more
Change log file for OpenEMM 2015 (text format)
Install file for native Windows version of OpenEMM 2013 (text format)
Install & Admin Guide for OpenEMM 2015 (link to SourceForge)
User manual for OpenEMM 2013 (link to SourceForge)
Documentation of OpenEMM Script Actions (link to SourceForge)
Documentation of OpenEMM web service API 1.0 (link to SourceForge)
Documentation of OpenEMM web service API 2.0 (link to SourceForge)
Documentation of OpenEMM extension interface and database schema (for developers) (link to SourceForge)
Setup Guide for OpenEMM 2013 Virtual Machine (for Windows and Linux) (link to SourceForge)
You are a developer and interested in further source code documentation to improve OpenEMM?
More information can be found in our OpenEMM Wiki
Program and source code files
You will get source code and program code files via the following link:
OpenEMM downloads on SourceForge.net
- win32.zip file for Windows operating systems
- tar.gz tarball for all Linux distributions
- vmx files for the platform-independent VMware player
The win32.zip file was tested with Windows XP.
TheBinary Tarball was tested with Red Hat Linux, CentOS and Ubuntu.
The vmx.zip file was tested with VMware player.
Download from contributors
Simple Python client wrapper for new webservices (WS2) of OpenEMM, using the SUDS library
Code for Git on GitHub
PHP class that abstracts the interface of the legacy webservices of OpenEMM and provides the same functionality as native PHP code (beta version)
PHP class for OpenEMM
Joomla! 1.5 component to connect to OpenEMM
com_jopenemm.zip (search, change, add and delete subscribers as well as add and change mailinglists)
Joomla! 1.5 module to let users subscribe
ZuckerSync for OpenEMM to synchronize OpenEMM with SugarCRM (<5.2)
release candidate 1 of connector
FAQsFrequently asked questions
This website offers plenty of answers to FAQs to all users of OpenEMM. If your question hasn’t already been answered here, maybe you will find a solution for your subject in the OpenEMM forum!
How can I report bugs in OpenEMM
If you find a bug in OpenEMM, please submit a detailed description of the bug (so that we can reproduce it) to this bugtracker.
Your bug description should include at least the following information:
- bug description
- your Linux distribution, release and version
- the version of MySQL you use
- the version of OpenEMM you use
Depending on the nature of the bug this could be helpful:
- attachment with file /var/log/console_stderr.log
- attachment with file /var/log/console_stdout.log
Thank you for helping us improving OpenEMM!
What is a Hostname, a Domain and a FQND?
A Fully Qualified Domain Name (FQDN) links to an IP address of a server. The Internet address may be composed of letters and numbers, by using this option nobody has to remember the difficult number sequence (IP).
A FQDN is divided in three levels:
1) The appendage of the domain is the Top Level Domain (TLD). Example: net, com or eu
2) The domain name will be inserted in front of the TLD. Example: openemm or agnitas
3) At the very first stands the hostname. For webpages mostly: www
The FQDN www.yourcompany.com is composed of:
• www = hostname
• yourcompany = domain name
• com = TLD
As you can see, the FQDN consists of the hostname, the domain and the top level domain separated by dots. Finally the server IP address (i.e. 172.16.13.52) will be replaced by the addressable www.yourcompany.com address.
The FQDN can be expanded with a subdomain (i.e. miami). The subdomain will be inserted between the hostname and the domain name.
Why do you use Sendmail and not other MTAs?
In general, we prefer Sendmail over other MTAs because:
- Sendmail is widely-used on the Internet
- Sendmail is included in many distributions by default
- Security vulnerabilities are quickly discovered and fixed
- Sendmail is backed by a company which takes care of maintenance, support and further development
- At the time we developed the first version of OpenEMM’s commercial brother EMM (in 1999) Qmail was unusable for our purposes and Postfix was in its infancy
Sendmail is difficult to replace in OpenEMM by other MTAs because
- Spool files can easily be generated directly (the process is documented) – therefore, OpenEMM can assign spool file names so that OpenEMM has sufficient ID information encoded to use the names for bounce management during mail transmission
- Bounce management is based on a well documented plugin interface of Sendmail (milter) and permits combining the realibility of Sendmail with the flexibility of OpenEMM functions.
How can I install OpenEMM on Debian?
User “minichip” provided us with this guide on how to install OpenEMM on Debian 3.1 (sarge):
“Basically I used the file INSTALL.pdf, so I will point to the commands that differ from the manual.
> apt-get update
> apt-get install mysql-server-4.1 sendmail-cf python-mysqldb
It won’t work with mysql-4.0
Java, nothing Debian specific here. I used ‘jdk-1_5_0_08-linux-i586.bin’ as it is the latest version. Every command listed in the manual worked on Debian.
If no firewall is used, this part can be skipped, otherwise the user should be experienced enough to manage it and activate it on start up. So here are the basic commands which will get you started.
iptables -A INPUT -m state –state NEW -m tcp -p tcp –dport 25 -j ACCEPT
iptables -A INPUT -m state –state NEW -m tcp -p tcp –dport 80 -j ACCEPT
iptables -A INPUT -m state –state NEW -m tcp -p tcp –dport 8080 -j ACCEPT
iptables -A INPUT -m state –state NEW -m tcp -p tcp –dport 8081 -j ACCEPT
DNS, nothing Debian specific here.
Basically you try to set up an MX record for the domain bounce.somecompany.com which points to www.somecompany.com which itself should point to an IP address or is a CNAME.
Sendmail. This is my weak spot, as I never worked with it before and I’m still trying to manage the monster.
To be honest I currently have no mail boxes on the system, so I can’t say if the bounce feature works 100%, but I know that the bounce management works for emails that are rejected by the foreign email server during the smtp session, so it should work with bounce emails as well.
DAEMON_OPTIONS(`Family=inet, Name=MTA-v4, Port=smtp, Addr=127.0.0.1′)dnl
DAEMON_OPTIONS(`Family=inet, Name=MTA-v4, Port=smtp’)dnl
The rest stays the same as the Red Hat instructions.
Suse instructions work for Debian as well.
Check /etc/syslog.conf and change the path for the mail log from /var/log/mail.log to /var/log/maillog
savelog -g adm -m 640 -u root -c 4 $LOG >/dev/null
savelog -g adm -m 644 -u root -c 4 $LOG >/dev/null
Change permission for maillog
> chmod 644 /var/log/maillog
Red Hat instructions work for Debian.
Instructions work for Debian.
Didn’t used it as of now, but instructions should work for Debian, except the RPM part 😉
Put the following in your firewall script
iptables -A PREROUTING -t nat -p tcp -i eth+ –dport 80 -j REDIRECT –to-port 8080
End of minichip´s guide.
Comments on this guide posted by Benoit:
1. Make sure sendmail is not being started by the system rc scripts. OpenEMM itself will start sendmail and point it to it’s own spool directory. (took me hours to find out)
2. You must also edit mailer.sh to have the sendmail PID files put to the right place. In Debian Sendmail runs as root but has no permission to write to user homes. Fix: Edit mailer.sh and replace the right path. For Debian it should be -OPidFile=/var/run/sendmail/mta/
In case you have further questions you may find him on the OpenEMM support forums.
Is it possible to install OpenEMM on a managed server?
The precondition to install OpenEMM is
- a Linux server with a fix IP address and
- a SSH shell access with root user rights
You do not need a dedicated server, a virtual server (e.g. VMware) is adequate.
Is it possible to install OpenEMM via FTP?
No, it is not. To install OpenEMM you need SSH shell access with root user rights. FTP access is not sufficient.
Why does sending of mails not work (Linux only)?
This may have several reasons. To locate the problem you should check out these points in the noted sequence:
1.) Trivial case: You have chosen a target group with no recipient, so there is no mail to be sent (target groups are ignored during admin and test mail sending).
2.) If the MySQL DB does not run on localhost, if you changed the name of the database or the user or password, please adjust parameters dbhost, dbdatabase, dbuser, dbpass in file agn.py in directory /home/openemm/bin/scripts accordingly.
3.) Check whether the intermediate files are generated (not applicable for admin and test mails). These files are written to /home/openemm/var/spool/META and the filenames start with “AgnMail” and end with “xml.gz” (the data itself), “stamp” (a marker that the data file is complete) and “final” (the whole mailing is complete.)
As these files are only temporary, you can either stop the process pickdist (using the command /home/openemm/bin/pickdist.sh stop) during mail generation or check the ARCHIVE directory for generated files. Do not forget to restart pickdist (using /home/openemm/bin/pickdist.sh start) to restart pickdist, if stopped.
4.) Check for working pickdist. This process handles the intermediate files (not applicable for admin and test mails) and takes the necessary steps to generate the final spool files. First look in the processlist (ps -u openemm -f) if pickdist is running (depending on your screen width you may have to add the option -w to the ps command to see the full command line); you should find in the process list something like:
If pickdist is running, but the intermediate files are not processed, consult the logfile for pickdist for further informations in
5.) If mails are generated and written to /home/openemm/var/spool/ADMIN (admin and test mails only) or /home/openemm/var/spool/QUEUE (world mailings) you have to check for a working Sendmail. Therefore, you should consult log file /var/log/maillog to check for possible problems. If Sendmail tries to send mails you should see some hints here (but you can ignore messages like “unable to write pid to …: Permission denied”, because this does not stop sendmail from sending mails).
6.) Another reason for Sendmail not sending mails might be network problems. In this case stop OpenEMM with
su – openemm
re-establish the network connection with
and start OpenEMM again with
su – openemm
7.) If you use OpenEMM in a dial-up environment it may be possible that lots of internet providers and company server deny mails send directly from you (because of massive misuse by botnets). Very often this is indicated by bounce replies to the sender. If you are user root you can check for those bounce replies in file /var/spool/mail/root.
If it is possible for you to use a mailserver from your provider you should add this mailserver as the smart host in Sendmail adding this line to your sendmail.mc:
replacing “smtp.your.provider” with the name of your provider mail relay.
Recreate the sendmail.cf file by typically calling make in /etc/mail or /etc and restart OpenEMM. But please ask your provider BEFORE if he permits mass mailings send over his relay!
8.) Finally, as always, it is a good idea to scan the logfiles in /home/openemm/var/log for suspicious messages.
Comment posted by Benoit:
If Installing under Debian. Please make sure sendmail is not being started at system startup. Sendmail ist being started by the OpenEMM script and pointing to the Spool Directories within the OpenEMM Home. If sendmail is started by the rc scripts, it will point to the usual spool directory and never send emails.
Should I use Sendmail or the internal SMTP server of OpenEMM?
First, let’s take a look at the origin of the non sendmail solution. As OpenEMM is also available for Windows systems where no standard MTA is available, we needed some replacement. So we developed a simple sendmail emulation to do the required work to make OpenEMM usable.
Pros for the sendmail emulation:
- You have a closed system without the external dependency for an external package (sendmail.)
- The configuration is reduced to a minimum.
- You can run the whole application without root permission (as long as you ensure that a user may bind to port 25, which is not permitted by default.)
Cons for the sendmail emulation:
- It is written in Python, which is a great computer language, but it is still an interpreted language, which means it’s not optimized for speed and high load systems.
- It is limited to do the work for OpenEMM, nothing more. So if you need any other functionality a MTA offers (from simple deliver mails to other local mailboxes to complicate filter, relay or gateway you can’t realize this.
Pros for sendmail:
- It’s part of your operating system, so you will always get the latest or most stable version and it can serve all local users as well.
- As it is used by a broad user base it is well tested and reliable.
- You have all the feature sendmail offers (to get a clue, just look into your sendmail.cf.)
- It is written in a compiled language, so it’s fast and can handle high load.
Cons for sendmail:
- Local policy may prohibit the usage of sendmail. – Configuration can be very complicate (the price you pay for flexibility.)
- A bit more configuration work to set it up for OpenEMM.
So whenever possible, it makes more sense to use sendmail over the sendmail emulation as found in OpenEMM. If you cannot use sendmail, the emulation is still good enough for typical site.
Of course, this only makes sense on Linux, on Windows you will use the emulation, as there is no sendmail available (in general).
Why do I get an 404 not found error after installation?
Before launching OpenEMM with shell script OpenEMM.sh make sure to use su – openemm when changing to user openemm. The “-” is needed to include OpenEMM’s .bash_profile, which specifies the required environment variables.
Do I have to set up the bounce management?
Setting up the bounce management of OpenEMM is not necessary, since bounce management for bounces received during the send process (instant bounces) works out of the box. But if OpenEMM should even process bounces (and autoresponder mails) which are received hours or even days later (which is quite often the case) you have to do some setup.
How can I change the salutation?
You can define your own salutation in OpenEMM: Choose menu “Settings” and select menu item “Forms of address” (yes, bad wording, will be changed in the next release).
In your e-mail use the tag
Replace “1” with the number of the salutation you defined.
How can I change to a language other than English or German?
In order to get the OpenEMM interface working in other languages than English or German, first the file used to provide all text strings has to be translated.
Currently, in path /home/openemm/webapps/openemm/htdocs/WEB-INF/classes there are three language related files:
messages_en.properties – contains the English messages
messages_de.properties – contains the German messages
messages.properties – fallback version (contains english messages)
If you would like to use a different language for the OpenEMM interface, please translate one of the localized files – either messages_en.properties or messages_de.properties – to your desired language. After saving the file and restarting OpenEMM, you can test the new messages by choosing the corresponding language for your user (“Settings”/”User”/”Language”).
If you submit the translated message file to us, we will be glad to include it into the next release of OpenEMM so that all users can benefit from your work – thank you!
How can I use more than 120,000 addresses with OpenEMM?
If you want to work with more than 120,000 addresses in your database, you have to change the property import.maxrows in file emm.properties in directory /home/openemm/webapps/core/WEB-INF/classes accordingly.
However, the bigger your database, the more the performance of your OpenEMM installation will suffer.
How do I set up the bounce management for delayed bounces?
If you want to use the bounce management for delayed bounces you need to define a dedicated sender hostname for OpenEMM which is different from the existing host name of your server (see file “hosts” in directory “/etc”), and you have to set up a A record and a MX (Mail Exchanger) record in your Domain Name Server (DNS) for the sender hostname.
The MX record is used to route mail for a domain to one or more IP addresses. Sendmail needs the new (virtual) host as a destination, to forward all incoming response to, for further processing by OpenEMM.
In our example the regular hostname is ‘host’ and the sender hostname for OpenEMM will be ‘news’.
The (abbreviated) DNS entry looks like this:
86400 IN A 0 188.8.131.52
host 86400 IN A 10 184.108.40.206
news 86400 IN A 10 220.127.116.11
news.openemm.org. 86400 IN MX 10 host.openemm.org.
The first line assigns the IP address for openemm.org and the second line defines the regular hostname. The third and fourth line define the A record and the MX record for sender hostname ‘news’, meaning that host ‘host’ accepts e-mails sent to host ‘news’.
Validate your correct setup by using a tool like ‘host’ or ‘dig’, for example
host –a openemm.org
host –a host.openemm.org
host –a news.openemm.org
When you send e-mails and want to take advantage of the bounce management for delayed bounces there are two possibilities for the format of the sender address:
1.) Use whatever address you like. Set up a bounce filter in OpenEMM (see user manual) to forward the filtered response to a feedback e-mail address of your choice (different from the sender address, of course). Implement a forward mechanism to forward incoming mail sent back to the sender address to the e-mail address generated by the bounce filter (in our example email@example.com). The flow for responses of your e-mails works like this:
sender address -> filter-generated address (to filter out bounces) -> feedback address
2.) Use an e-mail address with the sender hostname (in our example firstname.lastname@example.org) Since no real e-mail addresses exist for the sender hostname, normally it would not be possible to reply to an e-mail with this ender address. To forward responses to a valid e-mail address you have to define a bounce filter with an e-mail feedback address of your choice. The e-mail address generated by the bounce filter (in our example email@example.com) has to be defined as an alias in directory /home/openemm/conf/bav in a new file named bav.conf-local. Our example:
The flow for responses of your e-mails works like this:
sender address -> bav.conf-local -> filter-generated address -> feedback address
If you create the file bav.conf-local please do not forget to re-create it after an update of OpenEMM – otherwise ist would be missing!
Is OpenEMM available with a German user interface?
Yes, you can change from English to German language.
In the left navigation bar click on menu “Settings” and choose submenu “User”. Select user “admin” and change the language field from English to German. Retype your password twice (field “Password” and “Confirm”) and press the “Save” button.
You have to log out and in again to activate the change of the user language.
Why does redirection of trackable links not work?
To make sure that the redirection of all trackable links in your e-mails works, you have to define the base URL for the OpenEMM redirect service in database table “company_tbl” in field “rdir_domain”. Please do not forget a leading “http://” or “https://” which is required by the OpenEMM redirect service.
During installation you can define the base URL by replacing the default URL “http://rdir.de” in file openemm.sql which is used to fill the database with initial data.
What is my CompanyID?
Your CompanyID is always 1. This is a fix value for upward compatibility and should not be changed!
What should I do if I experience a Java.lang.OutOfMemoryError: Java heap space?
If you work with big lists and experience an error message like “Java.lang.OutOfMemoryError: Java heap space”, you have to allocate more memory to the Java Virtual machine (JVM). You can increase the minimum and maximum memory in file httpd.sh in directory /home/openemm/bin by expanding the args parameter like this:
If you have allocated all memory available and the error remains, you should increase your RAM to at least 1 GByte (better: 2 GByte) and modify the args parameter accordingly.
###AGNUID### tag does not seem to work
Mailings must be sent (as test mailings) to check for the replacement of the ###AGNUID### tag. Simply checking in the preview window does not work (and showing the uid code would not be of value, anyway, since it would be non-clickable).
$customerData.* tags are not interpreted by OpenEMM
To access database fields via the $customerData tag all field names have to be quoted lower case, i.e. $customerData.email and not $customerData.EMAIL.
How can I use data fields within a link?
If you want to transfer individual data of the profile of a recpient via link, the notation for the data field is different from the notation of data fields within the text body of an e-mail.
Within the text body of an e-mail you include the contents of data fields like this:
This e-mail was sent to address [agnEMAIL]
But within links (which are parsed not by EMM but by the webserver first) you have to include the field name like this:
Of course, you can use other field names than EMAIL – as long as a field of this name exists within the the recpient profile data set.
I can not deselect checkboxes when I define new actions?
When a step with a checkbox is added to an action and the checkbox is enabled, it can not be disabled again.
To work around this, remove the step from the action and add it again. The new step will have checkboxes disabled by default.
I can not preview mailings because the pull down menu is empty
To populate the pull down menu list of the preview menu with addresses of recipients, those recipoients have to be defined as “Test recipients” in the database field “Type” of their profile (recipient ⇒ overview ⇒ klick on profile).
I forgot my password for OpenEMM
This is the way to reset OpenEMM to its default password “openemm”:
mysql -u root [-p if password exists]
update admin_tbl set pwd_hash = 0x9bd796996fcdf40ad3d86025c03f2c9e where username = “admin”;
If you want to set the password to a specific phrase like “secret”:
mysql -u root [-p if password exists]
update admin_tbl set pwd_hash = 0x5ebe2294ecd0e0f08eab7690d2a6ee69 where username = “admin”;
The alphanumeric code which is prefixed by 0x (to tag the following code as hex code) is generated by the preceding select md5() statement.
I want to define an action, but the list box for action based mailings is empty
First, you have to create an action based mailing (Mailings -> New mailing), which you probably have done already.
Secondly, you have to activate an action based mailing via “activate mailing” in the “Send mailing” tab. This is necessary because otherwise you will get lost if you have defined a larger number of action based mailings.
I want to register individual-relates link clicks
Please follow these 3 steps:
1. Define a new numeric data field “linkclicks” (or use any other name) with default value 0 for the profile of your addresses.
2. Set up an action “clickcount” which sets the content of the field “linkclicks” to 1 (to register link clicks in general) or adds a value like +1 (to actually count link clicks).
3. When creating a mailing use the “trackable links” tab to connect action “clickcount” with the link for which you want to monitor clicks.
From then on you can go to Recipient / Overview, using search filter “clickcount > 0” and list all persons who clicked.
Reporting und BugfixingNobody is perfect but we try to get better and better
How to report bugs:
If you think you have found a bug, but you are a little bit unsure, please use our support forum Bugs, bug fixes & releases.
If you want to report a new bug in the latest version of OpenEMM, please use the OpenEMM bugtracker, select “OpenEMM” in the Group field and the appropriate version in the field “Category”.
Your bug description should include at least the following information:
- Bug description
- Your Linux distribution, release and version (or Windows version)
- The version of Tomcat you use
- The version of MySQL you us
- Last not least: the version of OpenEMM you use
Depending on the nature of the bug this could be helpful:
- Attachment with file /home/openemm/logs/catalina.out (Tomcat’s log)
- Attachment with file /var/log/maillog (Sendmail’s log)
Thank you for helping us improving OpenEMM!
Bug status and prioritization
We use the OpenEMM bugtracker hosted on SourceForge for public bug reports regarding OpenEMM.
There are four types of bugs in the bug tracker, which differ in their status:
1. Pending: Bug reports with pending status are not confirmed by the development team (yet) or need more feedback.
2. Open: Bug reports with open status are acknowledged by the development team and will be fixed as soon as possible.
3. Closed: Bug reports with closed status are already fixed in the latest release.
4. Deleted: Bug reports with deleted status have been reviewed by the development team and were rejected.
Confirmed bugs with priority 1 to 3 are minor and will be fixed in the next major release of OpenEMM. Bugs of priority 4 to 6 are major and will be fixed in the next bugfix release of OpenEMM and a separate bugfix will be provided as well (announcement via Twitter). Bugs with priority 7 to 9 are critical and will be fixed as soon as possible via a bugfix and with an extra release.
Bugfixes for OpenEMM
We publish bugfixes in subdirectoy “Bugfixes” of the OpenEMM directory with the corresponding version number in the file download area of SourceForge.
If you want to get notified about the availability of bugfixes for OpenEMM please subscribe to our Twitter log at www.twitter.com/openemm.
Official partner of OpenEMMExternal consulting- and support services
This is a list of companies (Partner) offering local OpenEMM consulting and support, sorted by country:
go-mobile IT GmbH
Speisinger Straße 76/1/10
(go-mobile is developer of the SugarCRM connector for OpenEMM)