Frequently asked questions (FAQs)
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!
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!
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. Example:
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.
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.
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.
No, it is not. To install OpenEMM you need SSH shell access with root user rights. FTP access is not sufficient.
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.
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.)
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.
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.
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.
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!
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.
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 126.96.36.199
host 86400 IN A 10 188.8.131.52
news 86400 IN A 10 184.108.40.206
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 it would be missing!
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.
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.
Your CompanyID is always 1. This is a fix value for upward compatibility and should not be changed!
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.
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).
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.
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:
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.
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.
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).
This is the way to reset OpenEMM to its default password "openemm":
The alphanumeric code which is prefixed by 0x (to tag the following code as hex code) is generated by the preceding select md5() statement.
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.
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.