Mailtrain is a self hosted newsletter application built on Node.js (v14+) and MySQL (v8+) or MariaDB (v10+).
This is version 2 of Mailtrain. It mostly implements all features of v1 and add some more. It is a complete rewrite, so you will have to install it from scratch.
If you are upgrading from Mailtrain v1, backup the DB and use it for Mailtrain v2. Mailtrain v2 should be able to upgrade the DB to the new schema.
- Subscriber lists management
- List segmentation
- Custom fields
- Email templates (including MJML-based templates)
- Custom reports
- Automation (triggered and RSS campaigns)
- Multiple users with granular user permissions and flexible sharing
- Hierarchical namespaces for enterprise-level situations
- Builtin Zone-MTA (https://github.com/zone-eu/zone-mta) for close-to-zero setup of mail delivery
- 2 vCPU
- 4096 MB RAM
Mailtrain creates three URL endpoints, which are referred to as "trusted", "sandbox" and "public". This allows Mailtrain to guarantee security and avoid XSS attacks in the multi-user settings. The function of these three endpoints is as follows:
- trusted - This is the main endpoint for the UI that a logged-in user uses to manage lists, send campaigns, etc.
- sandbox - This is an endpoint not directly visible to a user. It is used to host WYSIWYG template editors.
- public - This is an endpoint for subscribers. It is used to host subscription management forms, files and archive.
The recommended deployment of Mailtrain would use 3 DNS entries that all points to the same IP address. For example as follows:
- lists.example.com - public endpoint (A record
lists
underexample.com
domain) - mailtrain.example.com - trusted endpoint (CNAME record
mailtrain
underexample.com
domain that points tolists
) - sbox-mailtrain.example.com - sandbox endpoint (CNAME record
sbox-mailtrain
underexample.com
domain that points tolists
)
This will setup a publicly accessible Mailtrain instance. All endpoints (trusted, sandbox, public) will provide both HTTP (on port 80) and HTTPS (on port 443). The HTTP ports just issue HTTP redirect to their HTTPS counterparts.
The script below will also acquire a valid certificate from Let's Encrypt. If you are hosting Mailtrain on AWS or some other cloud provider, make sure that before running the installation script you allow inbound connection to ports 80 (HTTP) and 443 (HTTPS).
Note, that this will automatically accept the Let's Encrypt's Terms of Service. Thus, by running this script below, you agree with the Let's Encrypt's Terms of Service (https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf).
-
Login as root. (I had some problems running npm as root on CentOS 7 on AWS. This seems to be fixed by the seemingly extraneous
su
withinsudo
.)sudo su -
-
Install GIT
For Centos 7 type:
yum install -y git
For Ubuntu 18.04 LTS type
apt-get install -y git
-
Download Mailtrain using git to the
/opt/mailtrain
directorycd /opt git clone https://github.com/Mailtrain-org/mailtrain.git cd mailtrain git checkout v2
-
Run the installation script. Replace the urls and your email address with the correct values. NOTE that running this script you agree Let's Encrypt's conditions.
For Centos 7 type:
bash setup/install-centos7-https.sh mailtrain.example.com sbox-mailtrain.example.com lists.example.com [email protected]
For Ubuntu 18.04 LTS type:
bash setup/install-ubuntu1804-https.sh mailtrain.example.com sbox-mailtrain.example.com lists.example.com [email protected]
-
Start Mailtrain and enable to be started by default when your server starts.
systemctl start mailtrain systemctl enable mailtrain
-
Open the trusted endpoint (like
https://mailtrain.example.com
) -
Authenticate as
admin
:test
-
Update your password under admin/Account
-
Update your settings under Administration/Global Settings.
-
If you intend to sign your email by DKIM, set the DKIM key and DKIM selector under Administration/Send Configurations.
This will setup a locally accessible Mailtrain instance (primarily for development and testing). All endpoints (trusted, sandbox, public) will provide only HTTP as follows:
- http://localhost:3000 - trusted endpoint
- http://localhost:3003 - sandbox endpoint
- http://localhost:3004 - public endpoint
-
Login as root. (I had some problems running npm as root on CentOS 7 on AWS. This seems to be fixed by the seemingly extraneous
su
withinsudo
.)sudo su -
-
Install git
For Centos 7 type:
yum install -y git
For Ubuntu 18.04 LTS type:
apt-get install -y git
-
Download Mailtrain using git to the
/opt/mailtrain
directorycd /opt git clone https://github.com/Mailtrain-org/mailtrain.git cd mailtrain git checkout v2
-
Run the installation script. Replace the urls and your email address with the correct values. NOTE that running this script you agree Let's Encrypt's conditions.
For Centos 7 type:
bash setup/install-centos7-local.sh
For Ubuntu 18.04 LTS type:
bash setup/install-ubuntu1804-local.sh
-
Start Mailtrain and enable to be started by default when your server starts.
systemctl start mailtrain systemctl enable mailtrain
-
Open the trusted endpoint http://localhost:3000
-
Authenticate as
admin
:test
This setup starts a stack composed of Mailtrain, MongoDB, Redis, and MariaDB. It will setup a locally accessible Mailtrain instance with HTTP endpoints as follows.
- http://localhost:3000 - trusted endpoint
- http://localhost:3003 - sandbox endpoint
- http://localhost:3004 - public endpoint
To make this publicly accessible, you should add reverse proxy that makes these endpoints publicly available over HTTPS. If using the proxy, you also need to set the URL bases and --withProxy
parameter via MAILTRAIN_SETTING
as shown below.
An example of such proxy would be:
- http://localhost:3000 -> https://mailtrain.example.com
- http://localhost:3003 -> https://sbox-mailtrain.example.com
- http://localhost:3004 -> https://lists.example.com
To deploy Mailtrain with Docker, you need the following two dependencies installed:
These are the steps to start Mailtrain via docker-compose:
-
Download Mailtrain's docker-compose build file
curl -O https://raw.githubusercontent.com/Mailtrain-org/mailtrain/v2/docker-compose.yml
-
Deploy Mailtrain via docker-compose (in the directory to which you downloaded the
docker-compose.yml
file). This will take quite some time when run for the first time. Subsequent executions will be fast.docker-compose up
-
Open the trusted endpoint http://localhost:3000
-
Authenticate as
admin
:test
The instructions above use an automatically built Docker image on DockerHub (https://hub.docker.com/r/mailtrain/mailtrain). If you want to build the Docker image yourself (e.g. when doing development), use the docker-compose-local.yml
located in the project's root directory.
This setup starts a stack like above, but is tweaked to be used for local development using docker containers.
-
Clone this repository
-
Bring up the development stack
docker-compose -f docker-compose-develop.yml up -d
-
Connect to a shell inside the container
docker-compose exec mailtrain bash
-
Run these commands once to install all the node modules and build the client webapp
cd /app bash setup/reinstall-modules.sh cd /app/client && npm run build && cd /app
-
Start the server for the first time with this command, to generate the
server/config/production.yaml
bash docker-entrypoint.sh
When using Docker, you can override the default Mailtrain settings via the following environment variables. These variables have to be defined in the docker-compose config
file. You can give them a value directly in the docker-compose.yml
config file.
Alternatively, you can just declare them there leaving their value empty
(see https://docs.docker.com/compose/environment-variables/#pass-environment-variables-to-containers). In that case, the
value can be provided via a file called .env
or via environment
variables (e.g. URL_BASE_TRUSTED=https://mailtrain.domain.com (and more env-vars..) docker-compose -f docker-compose.yml build (or up)
)
!!!WARNING!!! Always set ADMIN_PASSWORD, as it will leave your instance otherwise vurnerable with the default password being test
!
Parameter | Description |
---|---|
ADMIN_PASSWORD | sets Admin Password, Admin users name can be changed, but password will always be overwritten by this, please set it always, as it otherwise defaults to test |
ADMIN_ACCESS_TOKEN | sets Access Token for API, this is optional |
PORT_TRUSTED | sets the trusted port of the instance (default: 3000) |
PORT_SANDBOX | sets the sandbox port of the instance (default: 3003) |
PORT_PUBLIC | sets the public port of the instance (default: 3004) |
URL_BASE_TRUSTED | sets the external trusted url of the instance (default: http://localhost:3000), e.g. https://mailtrain.example.com |
URL_BASE_SANDBOX | sets the external sandbox url of the instance (default: http://localhost:3003), e.g. https://sbox-mailtrain.example.com |
URL_BASE_PUBLIC | sets the external public url of the instance (default: http://localhost:3004), e.g. https://lists.example.com |
WWW_HOST | sets the address that the server binds to (default: 0.0.0.0) |
WWW_PROXY | use if Mailtrain is behind an http reverse proxy (default: false) |
WWW_SECRET | sets the secret for the express session (default: $(pwgen -1) ) |
MONGO_HOST | sets mongo host (default: mongo) |
WITH_REDIS | enables or disables redis (default: true) |
REDIS_HOST | sets redis host (default: redis) |
REDIS_PORT | sets redis host (default: 6379) |
MYSQL_HOST | sets mysql host (default: mysql) |
MYSQL_PORT | sets mysql port (default: 3306) |
MYSQL_DATABASE | sets mysql database (default: mailtrain) |
MYSQL_USER | sets mysql user (default: mailtrain) |
MYSQL_PASSWORD | sets mysql password (default: mailtrain) |
WITH_LDAP | use if you want to enable LDAP authentication |
LDAP_HOST | LDAP Host for authentication (default: ldap) |
LDAP_PORT | LDAP port (default: 389) |
LDAP_SECURE | use if you want to use LDAP with ldaps protocol |
LDAP_BIND_USER | User for LDAP connexion |
LDAP_BIND_PASS | Password for LDAP connexion |
LDAP_FILTER | LDAP filter |
LDAP_BASEDN | LDAP base DN |
LDAP_UIDTAG | LDAP UID tag (e.g. uid/cn/username) |
WITH_ZONE_MTA | enables or disables builtin Zone-MTA (default: true) |
POOL_NAME | sets builtin Zone-MTA pool name (default: os.hostname()) |
WITH_CAS | use if you want to use CAS |
CAS_URL | CAS base URL |
CAS_NAMETAG | The field used to save the name (default: username) |
CAS_MAILTAG | The field used to save the email (default: mail) |
CAS_NEWUSERROLE | The role of new users (default: nobody) |
CAS_NEWUSERNAMESPACEID | The namespace id of new users (default: 1) |
LOG_LEVEL | sets log level among `silly |
DEFAULT_LANGUAGE | sets default language (default: en-US) |
WITH_POSTFIXBOUNCE | enables PostfixBounce TCP listener (default: false) |
POSTFIXBOUNCE_PORT | sets PostfixBounce Listening TCP-Port (default: 5699) |
POSTFIXBOUNCE_HOST | sets PostfixBounce Listening Host (default: 127.0.0.1) |
If you don't want to modify the original docker-compose.yml
, you can put your overrides to another file (e.g. docker-compose.override.yml
) -- like the one below.
version: '3'
services:
mailtrain:
environment:
- URL_BASE_TRUSTED
- URL_BASE_SANDBOX
- URL_BASE_PUBLIC
getMultiCampaignQuickStatistics(campaign)
Name: Custom multi-campaigns quick total stats
Type: html
Namespace: choose your namespace
User selectable fields:
[
{
"id": "campaign",
"name": "Campaign",
"type": "campaign",
"minOccurences": 1,
"maxOccurences": 1000
}
]
Data processing code:
const results = await campaigns.getMultiCampaignQuickStatistics(inputs.campaign, ["*"]);
// Uncomment to see results data
//console.log(`results: ${JSON.stringify(results)}`)
render({ results })
Rendering template:
<h2>{{title}}</h2>
<div class="table-responsive">
<table class="table table-bordered table-hover" width="100%">
<thead>
<th>
Campaign
</th>
<th>
Subject
</th>
<th>
Send configuration
</th>
<th>
Delivered
</th>
<th>
Opened
</th>
<th>
Clicked
</th>
<th>
Unsubscribed
</th>
<th>
Bounced
</th>
<th>
Complained
</th>
</thead>
{{#if results}}
<tbody>
{{#each results}}
<tr>
<th scope="row">
<a href="https://mailtrain.grasii.club/campaigns/{{id}}/status">{{name}}</a>
</th>
<td style="width: 12%;">
{{subject}}
</td>
<td style="width: 12%;">
{{send_configuration}}
</td>
<td style="width: 12%;">
{{delivered}}
</td>
<td style="width: 12%;">
{{opened_percent}}% ({{opened}})
</td>
<td style="width: 12%;">
{{clicks_percent}}% ({{clicks}})
</td>
<td style="width: 12%;">
{{unsubscribed_percent}}% ({{unsubscribed}})
</td>
<td style="width: 12%;">
{{bounced_percent}}% ({{bounced}})
</td>
<td style="width: 12%;">
{{complained_percent}}% ({{complained}})
</td>
</tr>
{{/each}}
</tbody>
{{/if}}
</table>
</div>
Name: Custom multi-campaigns quick total stats
Report template: Custom multi-campaigns quick total stats
Campaing: Allows you to select mutliple campaings
Clikcs on Save and leave
and then Refresh report
to see the magic
getMultiCampaignMessagesStatistics(campaign, startBeforeDays, endBeforeDays, groupByCampaingIds = true, debug = false)
Name: Custom getMultiCampaignMessagesStatistics, 0-30 days before
Type: html
Namespace: choose your namespace
User selectable fields:
[
{
"id": "campaign",
"name": "Campaign",
"type": "campaign",
"minOccurences": 1,
"maxOccurences": 1000
}
]
Data processing code:
const startBeforeDays = 30;
const endBeforeDays = 0;
const debug = false;
const groupByCampaingIds = true;
const results = await campaigns.getMultiCampaignMessagesStatistics(inputs.campaign, startBeforeDays, endBeforeDays, groupByCampaingIds, debug);
// Uncomment to see results
//console.log(`results: ${JSON.stringify(results)}`)
render({ results })
Rendering template:
<h2>{{title}}</h2>
<p>*represents the values since the beginning of the campaign</p>
</br>
<div class="table-responsive">
<table class="table table-bordered table-hover" width="100%">
<thead>
<th>
Campaign
</th>
<th>
Subject
</th>
<th>
Send configuration
</th>
<th>
Delivered
</th>
<th>
Opened
</th>
<th>
Clicked
</th>
<th>
Delivered*
</th>
<th>
Unsubscribed*
</th>
<th>
Bounced*
</th>
<th>
Complained*
</th>
</thead>
{{#if results}}
<tbody>
{{#each results}}
<tr>
<th scope="row">
<a href="https://mailtrain.grasii.club/campaigns/{{id}}/status">{{name}}</a>
</th>
<td style="width: 12%;">
{{subject}}
</td>
<td style="width: 12%;">
{{send_configuration}}
</td>
<td style="width: 12%;">
{{delivered}}
</td>
<td style="width: 12%;">
{{opened_percent}}% ({{opened}})
</td>
<td style="width: 12%;">
{{clicks_percent}}% ({{clicks}})
</td>
<td style="width: 12%;">
{{delivered_total_from_beginning}}
</td>
<td style="width: 12%;">
{{unsubscribed_total_from_beginning_percent}}% ({{unsubscribed_total_from_beginning}})
</td>
<td style="width: 12%;">
{{bounced_total_from_beginning_percent}}% ({{bounced_total_from_beginning}})
</td>
<td style="width: 12%;">
{{complained_total_from_beginning_percent}}% ({{complained_total_from_beginning}})
</td>
</tr>
{{/each}}
</tbody>
{{/if}}
</table>
</div>
Name: Custom getMultiCampaignMessagesStatistics, 0-30 days before
Report template: Custom getMultiCampaignMessagesStatistics, 0-30 days before
Campaing: Allows you to select mutliple campaings
Clikcs on Save and leave
and then Refresh report
to see the magic
GPL-V3.0