10 Advanced Configuration
This chapter describes some more advanced configuration options. Please be aware that you should backup first any files you modify in case the configuration is broken afterwards.
10.1 Mailloop Configuration
The mailloop service enables OpenEMM to process bounces (and autoresponder mails) which can be sent back to the sender address hours or even days after OpenEMM dispatched the mailing. We call these late bounces “asynchronous bounces”.
You need to define a dedicated mailloop service domain name which is different from the OpenEMM server hostname (set in /etc/sysconfig/network/). While you have to set up the A record for the OpenEMM server hostname, you have to set an MX (Mail Exchange) record for the mailloop service domain name, which points to the OpenEMM server hostname for correct mail routing.
For each new bounce filter created in the OpenEMM GUI, OpenEMM creates a new filter address, by default based on the mailloop service domain name. The OpenEMM user should define a mail forwarding for the address(es) used as sender address in its mailings, to direct all incoming response to the filter address(es) for further processing by the mailloop service (see “Alternative A” below).
In our example below the subdomain of the OpenEMM server hostname is openemm and the mailloop service subdomain name will be mailloop. The (abbreviated) DNS entry for domain.com should look like this:
Replace expression <ip address> with the IP address of the OpenEMM server, which also runs the mailloop service.
The first line assigns the IP address to the regular hostname, and the second line defines the MX record for the mailloop service domain name, meaning that host openemm accepts emails sent to host mailloop.
Validate your setup by using a tool like dig or host, for example
10.1.1 Bounce Filtering Alternatives
When you send emails and want to take advantage of the bounce management for asynchronous bounces, there are three possibilities to set up your bounce management filtering. This chapter explains the different options you have.
The sender address mentioned in the options below is the email address used as the sender address in your mailing or newsletter, i.e. the "From:" address (and it is also used as the "envelope from" address, if not explicitly configured otherwise).
The filter address is the email address hosted by the mailloop service, and it is configured in the GUI of OpenEMM (feature "bounce filter"). The default filter address is created as "reply_<unique number>" in the local part and with the domain name of the mailloop service. In the example below the domain name is "mailloop.domain.com", i.e. the standard filter address created at first would be reply_1@mailloop.domain.com.
The popular option (alternative A):
Use whatever sender address you like, example: news@agnitas.com. Create a filter address by setting up a bounce filter in OpenEMM (see user manual). This filter will auto-generate a filter address like reply_1@mailloop.domain.com.
Implement a forward mechanism in the email account of the sender address to forward incoming mail, which was sent back to the sender address, to the filter address of OpenEMM. If you use news@agnitas.com as sender address, set the forwarding for domain agnitas.com with
The flow of automated responses to your mailings (like autoresponder mails and bounce notifications) starts at the email address of the recipient, goes back from there to your sender address and is forwarded from the sender address to the filter address.
The advantage of this model is that you can choose any domain for the sender address you want, but you have to implement an external forward mechanism.
The advanced option (alternative B):
Use a sender address with the domain name of the mailloop service (for example news@mailloop.domain.com). Since no real email addresses exist for this sender domain name, normally it would not be possible to reply to an email with this sender address. To forward responses to a valid email address you have to define a bounce filter:
In the GUI configuration for the bounce filter set field Filter address manually to your individual sender address (in this example news@mailloop.domain.com) and this address is then bound to this bounce configuration. Due to performance reasons it may take a few minutes until a newly created entry is known by the system.
The flow of automated responses to your mailings (like autoresponder mails and bounce notifications) now goes directly from the email address of the recipient to your sender address, which is equal to the filter address of the bounce filter.
The advantage of this alternative is, that no external forward mechanism is needed, but your sender address has to use the domain name of your mailloop service. Also, you may not use policy "strict" for DMARC, since the FQDN of your mailloop service will differ from the FQDN of your mail server.
The sophisticated option (alternative C):
There is a third alternative for your filter configuration which allows you to set up a filter address of your own choice without having to implement an external forward mechanism. In this case you create a bounce filter with an individual filter address of your choice, like reply@yourdomain.com. Make sure that in the DNS record of the domain used in your filter address, the MX record points to your OpenEMM server like
Now you can use this filter address in a similar way as in alternative B, but with a different domain name (in this example: yourdomain.com). If you use SPF, make sure that the SPF record of this domain used in your filter address includes the domain of your OpenEMM server.
In this case the flow of automated responses to your mailings (like autoresponder mails and bounce notifications) goes directly from the email address of the recipient to your sender address, which is equal to the filter address of the bounce filter.
The advantage of this alternative is, that no external forward mechanism is needed like in alternative A and that the domain of the sender address and the filter address can differ opposed to alternative B.
Caveat: Alternatives B or C will not accept some reserved local parts as part of the filter address. These reserved local parts are currently
- reply_<number>
- aml_<number>
- fbl
10.2 Configuration of Default Settings
Menu Configuration, sub-menu Change configuration in DB allows you to change certain configuration parameters of the OpenEMM frontend like file paths, server addresses and limiting values. You should have a look at the list of parameters to understand which parameters can be changed.
In the section of parameters with prefix mailaddress you should define email addresses for support requests by your users and email addresses for certain notification mails. By default, these email addresses are set to an invalid sender domain and, therefore, would never leave the OpenEMM server.
Some parameters of interest can be modified directly in database table company_info_tbl. Parameters with prefix max limit certain resources to avoid an overload of the database and parameters with prefix expire define, after how many days certain entries are deleted from the database to limit the required storage space.
Table config_tbl holds additional parameters valid for the instance of OpenEMM, especially URLs and file paths to components used by OpenEMM as well as system email addresses.
If the OpenEMM database holds more than 10,000 recipients and you open the recipient list you will be greeted with message The option you selected is too large to be displayed completely. Please limit your selection to reduce the amount of recipients.
If you want more than 10,000 recipients to be processed for the recipient list (which will take longer to display), set field max_recipients in database table company_tbl to the value you want:
To increase security, OpenEMM blocks logins when the same IP address generates a certain number of failed logins. The default value for the maximum number of failed logins is 10 and the default value for the lock out time is 60 seconds. You can change both values in the database with a new entry in table config_tbl. Examples for max. 3 retries and 5 minutes lock time:
INSERT INTO config_tbl (class, name, value, creation_date, change_date) VALUES (‘loginTracking’, ‘webui.maxFails’, ‘3’, current_timestamp, current_timestamp);
INSERT INTO config_tbl (class, name, value, creation_date, change_date) VALUES (‘loginTracking’, ‘webui.ipBlockTimeSeconds’, ‘300’, current_timestamp, current_timestamp);
We recommend that you set a HSTS header (HTTP Strict Transport Security) for the responses of OpenEMM. This ensures that the browser of the OpenEMM user always uses the secure HTTPS protocol to connect with the frontend of OpenEMM and no longer permit the use of the insecure HTTP protocol.
To activate this header, use this SQL code:
INSERT INTO http_response_headers_tbl (header_name, header_value, overwrite) VALUES ('Strict-Transport-Security', 'max-age=15768000', 1);
the max-age parameter defines the validity period ot this header in seconds.
If you are really into it, have a look at the source code of class ConfigValue.java to see, what else you can configure in OpenEMM.
If any change to the database configuration of OpenEMM does not come into effect within 5 minutes, you have to restart OpenEMM.
10.3 Configuration of Webservices
The webservice interface runs as a separate web application in directory /home/openemm/webapps/webservices.
After OpenEMM has been launched you may request the WSDL file for the webservices via URL
To be able to access the webservices of OpenEMM you have to create a webservice user with a password first. See the user manual for details.
10.4 Configuration of DKIM Support
OpenEMM supports DKIM keys as an essential standard to improve the deliverability of emails. DKIM key configuration and administration is done by two shell scripts in directory /home/openemm/bin:
- dkim-creat lets you create and implement new DKIM keys. Its syntax is
dkim-creat <domain> <selector> <length> - dkim-mgr is the core tool to maintain DKIM keys. It is used by dkim-creat.
To create a new DKIM key, launch dkim-creat as user merger in your working directory with 3 parameters:
- the domain for which a DKIM key should be created (<domain>)
- a selector like "emm" to identify the correct DKIM key (<selector>)
- the bit length of the key - we recommend 2.048 bits, maximum should be 4.096 bits (<length>)
Example:
dkim-creat generates three files in your current directory:
- <selector>@<domain>.pub, containing the public key
- <selector>@<domain>.priv, containing the private key
- install-<selector>@<domain>.sh, a little shell script to save your private DKIM key in the EMM database
Furthermore, dkim-creat shows the necessary configuration of the DKIM entry with the public DKIM key in the DNS record of your sender domain. Example:
Creating private/public key pair emm@agnitas.com.priv/emm@agnitas.com.pub for agnitas.com (selector emm) with 2048 bit
Installation sample for your DNS:
emm._domainkey.agnitas.com. IN TXT "v=DKIM1; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtWA2bIcq3n95h7hixhTDdSt2Bjcy209N7OOAHm/81lSY/PbkY7n5x5LELGvMuuOfg7QVChTM5dslDmJ2EHG8TSptZRuOPCw1fW2X3J8zkJK74wLSSVUoKWTYwefp7+WYfoY+XxLzc40DWS1kxYNSvO9KaKxctMYYiKruAtdpnDBuK/tEbTJZBBWH55vwTmXhYbX6L2ZsKIyKjueGfx7RTm3GrVAWRTpBo9krBbM0PL4dP8h3yySr9Hv/WwXk19qeaC0oksVKChiXpc8CCt1gdLWQ5FeqoKnc6LkMkl4th0gPY/voJB6EQA1BC5ZNbpYxgma1UEv1bG37iKV7hJ+LhQIDAQAB"
Creating install-emm@agnitas.com.sh .. add done.
Execute script install-<selector>@<domain>.sh after you have entered your new public DKIM key in the DKIM entry of the DNS record for your sender domain. The script then saves your private DKIM key into the OpenEMM database.
When you start dkim-mgr without parameters it shows you the OpenDKIM key entries in your EMM database in table dkim_key_tbl.
10.5 Configuration of a Smart Relay Server
To improve deliverability of your mailings or for security reasons it may make sense to use a smart relay to send out emails with OpenEMM.
To configure a smart relay for OpenEMM, define in Postfix configuration file main.cf in directory /etc/postfix/ line
where 192.168.0.1 is an example for the IP address of your smart relay server. You may also use the FQDN of your smart relay server instead of its IP address.
Please make sure that port 25 is open on your smart relay server and be advised that a smart relay complicates bounce management, especially if the MX entry of the DNS record for your sender domain does not point to your smart relay.
To make sure that the smart relay reports bounces back to EMM, you should define a forwarding configuration for the Postfix service on the smart relay server so that incoming bounces are forwarded to EMM. If the smart relay uses Postfix, we recommend a file mail-transport in directory /etc/postfix/ with this content:
news@domain1.com reply_1@mailloop.domain.com
news@domain2.com reply_2@mailloop.domain.com
news@domain3.com reply_3@mailloop.domain.com
In this example the left side shows the sender addresses you use for your emails and the right side shows the filter addresses created by OpenEMM (in GUI menu "Response Processing").
In Postfix configuration file main.cf in directory /etc/postfix/ add these two lines:
relay_domains = domain1.com, domain2.com, domain3.com
virtual_mailbox_maps = hash:/etc/postfix/mail-transport
to make sure that the map in file mail-transport is processed by Postfix.
Activate this new forwarding configuration with