Configuration

Configuring and running EmailEngine

EmailEngine works with two types of configurations:

  1. Application configuration, which loads when the application starts (for example, the HTTP port number to listen on).
  2. Runtime configuration, which can be updated through the Settings API endpoint and altered at any time (for example, webhooks destination URL). Most of these settings can also be changed using the built-in web interface.

You can set the application configuration through command-line arguments or environment variables. If both are provided, the environment variable will override the value from the command-line argument for the same setting.

Dotenv file

If the working directory has a "dotenv" file (named .env), EmailEngine uses it to set environment variables.

The dotenv file uses the KEY=VALUE format, with each entry on a separate line, like this:

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

Lines that start with # are considered 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
Max command duration --service.commandTimeout=10s EENGINE_TIMEOUT=10s 10s
Delay between creating each IMAP connection --service.setupDelay=0ms EENGINE_CONNECION_SETUP_DELAY=0ms 0ms
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
Submit Worker count --workers.submit=1 EENGINE_WORKERS_SUBMIT=1 1
Prepared settings --settings='{"JSON"}' EENGINE_SETTINGS='{"JSON"}' not set
Prepared access token --preparedToken="token..." EENGINE_PREPARED_TOKEN="token... not set
Prepared license key --preparedLicense="..." EENGINE_PREPARED_LICENSE="... not set
Encryption secret --service.secret="****" EENGINE_SECRET="****" not set
Chunk size for attachment download streams (in bytes) not available EENGINE_CHUNK_SIZE=1MB 1MB

IMAP Worker Count

You can either set a fixed number of threads to start (with the worker count defaulting to 4), or you can use the special value "cpus" that corresponds to the number of CPU threads available.

Example:

$ emailengine --workers.imap=cpus

Redis configuration

Database options.

Configuration option CLI argument ENV value Default
Redis connection URL --dbs.redis="url" EENGINE_REDIS="url" "redis://127.0.0.1:6379/8"
Key prefix not available EENGINE_REDIS_PREFIX="myprefix" not set

To run multiple EmailEngine instances on the same Redis server, make sure to use a different database number or unique key prefixes to avoid conflicts.

If you're working with a non-default Redis configuration, like when your Redis instance isn't installed locally or needs authentication, provide the Redis configuration as a connection string using this 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=5MB EENGINE_MAX_SIZE=5MB 5MB
Max POST body size when uploading messages --api.maxBodySize=50MB EENGINE_MAX_BODY_SIZE=50MB 50MB
CORS allowed origin --cors.origin="*" EENGINE_CORS_ORIGIN="*" not set
CORS max age --cors.maxAge=60s EENGINE_CORS_MAX_AGE=60s 60s

To specify multiple CORS origins, use a space-separated string value, or add a separate --cors.origin argument for each origin value.

Configuration option CLI argument ENV value Default
HTTPS enabled EENGINE_API_TLS="true" "false"
HTTPS private key --api.tls.keyPath="/key.pem" EENGINE_API_TLS_KEY_FILE="/key.pem"
HTTPS certificate chain --api.tls.certPath="/cert.pem" EENGINE_API_TLS_CERT_FILE="/cert.pem"

NB! Use HTTPS only if your reverse proxy and EmailEngine instances are on different servers. For localhost connections, prefer HTTP.

Queue settings

Concurrency options for queue handling.

By default, a queue worker handles one job at a time. If your queues are being processed too slowly, you can increase the concurrency counters. However, the trade-off is that events may not be processed in the correct order when concurrency is set higher than 1. So, only increase these values if maintaining the order of events isn't a top priority.

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

ENV values from files

Available since v2.22.4

You can also set individual environment variables from a file. To achieve this, provide the path to the file containing the value using an environment key with a _FILE suffix.

If an environment variable isn't set, EmailEngine checks for a file path variable for that key. If it finds one, EmailEngine attempts to read the value from the specified file.

In the example below, we supply the value for EENGINE_SECRET from a file located at "/path/to/secret.txt":

$ echo 'secretpass' > /path/to/secret.txt
$ export EENGINE_SECRET_FILE=/path/to/secret.txt
$ emailengine