REMP Mailer Skeleton

3.4.0 2024-01-23 14:01 UTC


This is a pre-configured skeleton of REMP Mailer application with simple installation.

Mailer serves as a tool for configuration of mailers, creation of email layouts and templates, and configuring and sending mail jobs to selected segments of users.



The simplest possible way is to run this application in docker containers. Docker Compose is used for orchestrating. Except of these two application, there is no need to install anything on host machine.

Recommended (tested) versions are:

Steps to install application within docker

  1. Get the application

    A) Using Composer:

    composer create-project --no-install remp/mailer-skeleton path/to/install
    cd path/to/install

    B) Using GitHub:

    git clone
    cd mailer-skeleton
  2. Prepare environment & configuration files

    cp .env.example .env
    cp app/config/config.local.neon.example app/config/config.local.neon
    cp docker-compose.override.example.yml docker-compose.override.yml

    No changes are required if you want to run application as it is.

    Note: nginx web application runs on the port 80. Make sure this port is not used, otherwise you will encounter error like this when initializing Docker:

    ERROR: for nginx  Cannot start service nginx: Ports are not available: listen tcp bind: address already in use

    In such case, change port mapping in docker-composer.override.yml. For example, the following setting maps internal port 80 to external port 8080, so the application will be available at

    # ...
          - "8080:80"
  3. Setup host

    Default host used by application is This domain should by pointing to localhost (, so add it to local /etc/hosts file. In addition, we recommend adding domain for testing. Use the following commands:

    echo '' | sudo tee -a /etc/hosts
    echo '' | sudo tee -a /etc/hosts
  4. Start Docker containers

    docker compose up

    You should see logs of starting containers. This may include errors, because application was not yet initialized. Enter the application docker container:

    # run from anywhere in the project
    docker compose exec mailer bash

    When inside the container, add required permissions:

    chmod -R a+rw temp log

    After that, choose and run one of the two installation options:

    • Fully ready application with demo data:

      make install-demo
    • No demo data:

      make install
  5. Log-in to Mailer

    Access application via web browser. Default configuration:

    IMPORTANT: Please run make install every time you update Mailer-skeleton using composer update.

Manual installation


  • PHP 8.1
  • MySQL 8
  • Redis 6.2


Clone this repository, go inside the folder and run the following to create configuration files from the sample ones:

cp .env.example .env
cp app/config/config.local.neon.example app/config/config.local.neon

Edit .env file and set up all required values such as database and Redis connections.

Now run the installation:

make install

As an alternative, run the following to include seeding of demo values in the installation:

make install-demo

Mailer demo overview

Default integrations

After the installation of Mailer skeleton, Mailer uses default (local) integrations that need to be replaced with real implementations before going live. The local integrations serve as references and defaults to allow sending testing emails without doing any extra work.


SimpleAuthenticator is responsible for authentication to the tool.

List of credentials is configured in config.local.neon file. Default credentials are:

  • Email:
  • Password: passphrase_change_me

Do not run Mailer publicly with SimpleAuthenticator using the default credentials.

Mailers integration

Outgoing emails are sent by SmtpMailer. To configure a different mailer (e.g. MailGun), consult the Mailers section in the documentation. Configuration of the SMTP mailer is loaded from config.local.neon, see the section local_configs (which overrides any configuration options stored in the database):

    default_mailer: remp_smtp
    remp_smtp_host: mailhog
    remp_smtp_port: 1025

Key remp_smtp_host points to mailhog. This is an internal docker address of the mailhog docker container. The container runs MailHog, which is a web based SMTP testing tool. Therefore, all emails sent from the Demo Mailer instance are captured by MailHog, and are easily viewable in the MailHog web interface at

User-base integration

Mailer depends on external authority to get information about users. As a default source of users, Dummy implementation of user provider is used. Provider lists 2 demo users (, See the documentation on how to implement different user provider.

Segment integration

To send a newsletter, Mailer needs to get a segment of users who should receive it. To complement default user-base integration, there's also Dummy implementation of segment provider, always returning the same segment with both demo users.

Debug mode

After the installation, Mailer is running in debug mode and all debug information is shown. Avoid running this mode in production. To disable this mode, change the value of ENV key in .env configuration file:

# previously was `local` (debug ON)

Basic scenario - send email to user segment

To test the Mailer functionality, we recommend going through the following basic scenario:

  1. Log-in to Mailer at URL
  2. Go to Jobs
  3. Click Add new job
  4. Select values in Include segments, Newsletter list, and Email A alternative inputs. Keep other inputs empty.
    • Demo values of Emails, Layouts and Newsletter lists are seeded by default in demo installation.
  5. Click Save and start button
  6. Wait approximately a minute, so Mailer processes the job. Check the job status at Jobs page.
  7. After the job is processed (status "DONE"), go to MailHog at and check that emails were successfully received.


Mailer-skeleton is ready for customization. Please see the mailer-module documentation for more information.

As a sample, mailer-skeleton provides app/Commands/SampleCommand.php, extending the Command class. It is registered as a new command in the config.local.neon file. Run it by connecting to the container:

docker compose exec mailer bash

and executing the command:

php bin/command.php mail:sample-command


Some known errors that have occurred and how to fix them.

Docker SMTP error "Cannot assign requested address"

In some cases (such as running containers for the first time), a docker container might end up reporting this error message. Simply restarting the problematic container should help.