[opensourcedex]

mailtrain is a free, open source marketing & customer engagement project written in JavaScript and released under GPL-3.0. It has 5,751 GitHub stars, 707 forks and 116 open issues, and was last pushed 12 months ago. On this registry it ranks #19 of 50 tracked projects in Marketing & Customer Engagement, with 5 head-to-head comparisons available.

What is mailtrain?

What it is

Mailtrain is a self hosted newsletter application built on Node.js (v14 or later) with MySQL (v8 or later) or MariaDB (v10 or later) as the data store. Version 2 is a complete rewrite that mostly implements all features of version 1 while adding more, so it must be installed from scratch; existing v1 databases can be backed up and reused, as Mailtrain v2 is able to upgrade the schema. The project lives in the JavaScript ecosystem and is distributed under the GPL-3.0 license, with roughly 5,752 stars, 708 forks and 116 open issues on its repository, which has been active for about ten years with the last push in October 2025.

The concrete problem it addresses is ownership of the newsletter pipeline. Rather than renting a hosted email marketing service, an operator runs the sending stack, the subscriber database and the public subscription pages on their own infrastructure. Mailtrain bundles a builtin Zone-MTA for close to zero setup of mail delivery, so the deployment does not require assembling a separate mail transfer agent before the first campaign can go out.

Key capabilities

  • Subscriber lists management for organizing and maintaining audiences.
  • List segmentation for splitting subscribers into targeted groups.
  • Custom fields for storing additional per-subscriber data.
  • Email templates, including MJML-based templates.
  • Custom reports for reviewing campaign and list activity.
  • Automation through triggered campaigns and RSS campaigns.
  • Multiple users with granular user permissions and flexible sharing.
  • Hierarchical namespaces for enterprise-level situations.
  • Builtin Zone-MTA for close to zero setup of mail delivery.

Who uses it and how

  • Operators running a public newsletter instance split across three URL endpoints: trusted for the logged-in management UI, sandbox for hosting WYSIWYG template editors, and public for subscription management forms, files and archives.
  • Deployments that map the three endpoints to three DNS entries all pointing at the same IP address, for example lists.example.com, mailtrain.example.com and sbox-mailtrain.example.com.
  • Organizations that need several users with granular permissions and flexible sharing across subscriber lists.
  • Enterprise setups that use hierarchical namespaces to separate work at scale.
  • Publishers who pair triggered campaigns and RSS campaigns with custom reports to review results.

Getting started

Clone the repository with git, check out the v2 branch, then run the HTTPS installation script — setup/install-centos7-https.sh or setup/install-ubuntu1804-https.sh — passing the trusted, sandbox and public URLs plus an admin email address, after which Mailtrain is started and enabled with systemctl start mailtrain and

project readme (upstream, from github) — read inline

Mailtrain v2

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.

Features

  • 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

Recommended minimal hardware Requirements

  • 2 vCPU
  • 4096 MB RAM

Quick Start

Preparation

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 under example.com domain)
  • mailtrain.example.com - trusted endpoint (CNAME record mailtrain under example.com domain that points to lists)
  • sbox-mailtrain.example.com - sandbox endpoint (CNAME record sbox-mailtrain under example.com domain that points to lists)

Installation on fresh CentOS 7 or Ubuntu 18.04 LTS (public website secured by SSL)

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).

  1. 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 within sudo.)

    sudo su -

  2. Install GIT

    For Centos 7 type:

    yum install -y git

    For Ubuntu 18.04 LTS type

    apt-get install -y git

  3. Download Mailtrain using git to the /opt/mailtrain directory

    cd /opt
git clone https://github.com/Mailtrain-org/mailtrain.git
cd mailtrain
git checkout v2

  4. 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]

  5. Start Mailtrain and enable to be started by default when your server starts.

    systemctl start mailtrain
systemctl enable mailtrain

  6. Open the trusted endpoint (like https://mailtrain.example.com)

  7. Authenticate as admin:test

  8. Update your password under admin/Account

  9. Update your settings under Administration/Global Settings.

  10. If you intend to sign your email by DKIM, set the DKIM key and DKIM selector under Administration/Send Configurations.

Installation on fresh CentOS 7 or Ubuntu 18.04 LTS (local installation)

This will setup a locally accessible Mailtrain instance (primarily for development and testing). All endpoints (trusted, sandbox, public) will provide only HTTP as follows:

  1. 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 within sudo.)

    sudo su -

  2. Install git

    For Centos 7 type:

    yum install -y git

    For Ubuntu 18.04 LTS type:

    apt-get install -y git

  3. Download Mailtrain using git to the /opt/mailtrain directory

    cd /opt
git clone https://github.com/Mailtrain-org/mailtrain.git
cd mailtrain
git checkout v2

  4. 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

  5. Start Mailtrain and enable to be started by default when your server starts.

    systemctl start mailtrain
systemctl enable mailtrain

  6. Open the trusted endpoint http://localhost:3000

  7. Authenticate as admin:test

Deployment with Docker and Docker compose

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.

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:

To deploy Mailtrain with Docker, you need the following two dependencies installed:

These are the steps to start Mailtrain via docker-compose:

  1. Download Mailtrain's docker-compose build file

    curl -O https://raw.githubusercontent.com/Mailtrain-org/mailtrain/v2/docker-compose.yml

  2. 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

  3. Open the trusted endpoint http://localhost:3000

  4. 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.

Deployment with Docker and Docker compose (for development)

This setup starts a stack like above, but is tweaked to be used for local development using docker containers.

  1. Clone this repository

  2. Bring up the development stack

    docker-compose -f docker-compose-develop.yml up -d

  3. Connect to a shell inside the container

    docker-compose exec mailtrain bash

  4. 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

  5. Start the server for the first time with this command, to generate the server/config/production.yaml

    bash docker-entrypoint.sh

Docker Environment Variables

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 pro

readme truncated — read the full docs on github

Frequently asked questions

Is mailtrain free to use?

mailtrain is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does mailtrain do?

Self hosted newsletter app

What is mailtrain written in?

mailtrain is primarily written in JavaScript. Its source is publicly available at https://github.com/Mailtrain-org/mailtrain, and it has 5,751 GitHub stars.