MailerQ Mimify
MailerQ-Mimify is an application to preprocess messages before they are picked up by MailerQ. The JSON messages that are normally read by MailerQ can first be processed by the MailerQ-Mimify application to create rich formatted emails based om properties inside the JSON.
Normally, MailerQ expects email messages to be formatted as MIME strings when they are injected into RabbitMQ. This means that before you inject a message into RabbitMQ/MailerQ, you must ensure that it is RFC2822 compliant. If you send the messages however first to the mimify application, you can leave the MIME generation up to MailerQ-Mimify, and focus just on the message content rather than the format.
Example input
For example, if you send the following JSON message through MailerQ-Mimify, it will be picked up and converted to full MIME:
{
"envelope": "johndoe@example.com",
"recipient": "info@example.com",
"mime": {
"subject": "This is my subject line",
"from": {
"name": "Joe Doe",
"address": "johndoe@exampel.com"
},
"to": {
"name": "Example Company",
"address": "info@example.com"
},
"content": "<html><body>Hello World!</body></html>",
"text": "Hello World!"
}
When MailerQ-Mimify reads out the above message from RabbitMQ, it converts it into a new JSON document and publishes it back to RabbitMQ in a MailerQ compatible format. The above document is for example converted into this:
{
"envelope": "johndoe@example.com",
"recipient": "info@example.com",
"mime": "MIME-Version: 1.0\r\nSubject: This is my subject line\r\nFrom:\r\n...."
}
For readability, we have shortened the full MIME string in the above example.
Features
The MailerQ-Mimify application supports many features:
- Support for all JSON properties listed on https://www.responsiveemail.com/json/introduction
- External resources like images and content feeds are on-the-fly downloaded
- MIME output is in valid RFC282 format and can be picked up by MailerQ
- Full responsive HTML and CSS creation based on properties from the JSON
- Messages are read from and published to RabbitMQ
- Downloads can be redirected via a caching proxy server
- Allows for a microservice based architecture
- Scalability: you can run multiple instances next to each other
The MailerQ-Mimify application was introduced in the beginning of 2024 to turn the MailerQ MTA into a more microservice oriented application. Up to version 5.14.*, MailerQ itself was capable of doing JSON-to-MIME conversion. However, as the number of mimify features grew, it was decided that the responsibility of generating MIME strings could better be handled by a standalone application.
Installation
The application is stored in our APT repository. If you have already enabled our APT repository, you can install it with this command:
sudo apt install mailerq-mimify
After that, you can run the application with the command mailerq-mimify. The configuration is normally picked up from its config file, but can also be given through command line arguments.
Configuration
All options can be supplied in the system wide config file, via environment variables, and as command line options. The config file is stored in /etc/copernica/mimify.txt. The following options are all equivalent:
- the setting "rabbitmq-address" in the /etc/copernica/mimify.txt config file
- the command line argument "--rabbitmq-address"
- the environment variable "MIMIFY_RABBITMQ_ADDRESS"
All other configuration settings can be converted in a similar manner.
Supported options for RabbitMQ
The mimify tool reads all instructions from a RabbitMQ message queue, and writes the results back to RabbitMQ. The following options can be used to configure this:
- rabbitmq-address: the address in amqp://user:password@hostname/vhost format.
- rabbitmq-input: name of the queue from which messages are read
- rabbitmq-output: name of the exchange to which processed messages are published
- rabbitmq-qos: number of messages to keep in memory (equals max number of conversion operations in progress)
Note that both the input and output queues can also be in "exchange:routingkey" format.
In a normal setup, you set the output address to MailerQ's inbox exchange and queue. This ensures that messages generated by MailerQ-Mimify are immediately delivered by MailerQ. The input address can be set to whatever queue where your own software stack publishes its messages to.
Download options
Inside the JSON you can refer to resources that are downloaded from external locations, like images or content feeds. To finetune the downloader, the following options are supported:
- download-useragent: User agent header, typical set to "Copernica Mimify"
- download-blacklist: Comma separated list of CIDR's, typical set to internal IPs like 127.0.0.1, 192.168.0.0/16, etc
- download-whitelist: Comma separated list of CIDR's, typical left empty, unless all downloads should be restricted to go through one IP
- download-proxy: URL of a proxy server in http:// or socks:// format
The blacklist and whitelist options can be used to restrict the IP addresses from which downloads are supported. If you keep the whitelist empty, downloads from all IP addresses are permitted, except for the blacklisted IP's. With a whitelist, downloads can only come from one of the listed IP's.
The proxy address can be set to a URL of a proxy server. The URL can be in the format "http://hostname:port" or "socks://hostname:port".
Webserver options
The mimify application runs a small webserver that exposes metrics in Prometheus format. It can be configured with the following config file settings:
- www-ip: IP address to listen to, use 0.0.0.0 to bind to all available IP's
- www-port: Port number of the webserver
The webserver only serves one page, a Prometheus compatible metrics page.