Configuration

Configuring and running EmailEngine

EmailEngine uses two kind of configurations:

  1. Application configuration that is loaded when the application starts (eg. the port number to listen on)
  2. Runtime configuration that is updated via the Settings API endpoint and can be modified at any time (eg. webhooks destination URL)

Application configuration can be set either via command line arguments or environment variables. If both are set then environment variable for the same thing overrides the value from the argument.

Dotenv file

If the working directory contains a dotenv file (a file named as .env) then EmailEngine uses it to populate environment variables.

Dotenv file uses KEY=VALUE syntax with each entry on a separate line, for example like this:

EENGINE_WORKERS=2
EENGINE_REDIS="redis://127.0.0.1:6379/8"

Lines starting with # are treated as comments and empty lines are ignored.

General settings

These are the main application settings

Configuration option CLI argument ENV value Default
IMAP Worker count --workers.imap=4 EENGINE_WORKERS=4 4
Redis connection URL --dbs.redis="url" EENGINE_REDIS="url" "redis://127.0.0.1:6379/8"
Prepared settings --settings='{"JSON"}' EENGINE_SETTINGS='{"JSON"}' not set
Encryption secret --service.secret="****" EENGINE_SECRET="****" not set
Local addresses --service.localAddresses="ip1,ip2" EENGINE_ADDRESSES="ip1,ip2" default interface
Max command duration --service.commandTimeout=10s EENGINE_TIMEOUT=10s 10s
Log level --log.level="level" EENGINE_LOG_LEVEL=level "trace"
Log raw data --log.raw=false EENGINE_LOG_RAW=false false
Webhook Worker count --workers.webhooks=1 EENGINE_WORKERS_WEBHOOKS=1 1

Redis configuration

If you are using non-default Redis configuration, for example if your Redis instance is not installed locally or requires authentication, then you can provide Redis configuration as a connection string in the following format:

redis://:password@hostname:port/db-number

Example:

$ emailengine --dbs.redis="redis://:supersecret@178.32.207.71:6379/8"

API server settings

Web server settings for the API and web UI

Configuration option CLI argument ENV value Default
Host to bind to --api.host="1.2.3.4" EENGINE_HOST="1.2.3.4" "127.0.0.1"
Port to bind to --api.port=port EENGINE_PORT=port 3000
Max attachment size --api.maxSize=5M EENGINE_MAX_SIZE=5M 5M
API Basic Auth --api.auth="user:pass" EENGINE_AUTH="user:pass" not set

Queue settings

Concurrency options for queue handling

By default a queue worker processes a single job at a time. If your queues are processed too slowly you can increase the concurrency counters. Downside is that events are not guaranteed to be processed in the correct order when having concurrency higher than 1, so increase these values only when you do not care about ordering too much.

Configuration option CLI argument ENV value Default
Webhooks concurrency count --queues.notify=1 EENGINE_NOTIFY_QC=1 1
Submit concurrency count --queues.submit=1 EENGINE_SUBMIT_QC=1 1

Increasing worker count also increases job processors count: worker_count * concurrency_count = parallel_job_processors

SMTP server settings

MTA for outbound emails

NB! SMTP server is disabled by default

Read more about using EmailEngine for email delivery

Configuration option CLI argument ENV value Default
SMTP enabled --smtp.enabled=true EENGINE_SMTP_ENABLED=true false
SMTP password --smtp.secret=pass EENGINE_SMTP_SECRET=pass ""
Host to bind to --smtp.host="1.2.3.4" EENGINE_SMTP_HOST="1.2.3.4" "127.0.0.1"
Port to bind to --smtp.port=port EENGINE_SMTP_PORT=port 2525
Behind HAProxy --smtp.proxy=true EENGINE_SMTP_PROXY=true false

When authenticating via SMTP use the account Id as the username and SMTP password value as the password to send emails using the selected account.

Special purpose headers

When sending emails via the SMTP service you can use the following headers:

  • X-EE-Send-At: timestamp to schedule sending to a future time. This matches sendAt property of the POST /submit API endpoint.

Bull Arena settings

Webhooks queue administration

Arena is a web based UI for Bull.js (the queue system EmailEngine internally uses)

NB! Arena server is disabled by default

Configuration option CLI argument ENV value Default
Arena enabled --arena.enabled=true EENGINE_ARENA_ENABLED=true false
Host to bind to --arena.host="1.2.3.4" EENGINE_ARENA_HOST="1.2.3.4" "127.0.0.1"
Port to bind to --arena.port=port EENGINE_ARENA_PORT=port 3001