Configuration

Configuring and running EmailEngine

EmailEngine uses two kinds of configurations:

  1. Application configuration that is loaded when the application starts (e.g., the port number to listen on)
  2. Runtime configuration that is updated via the Settings API endpoint and can be modified at any time (e.g., webhooks destination URL). You can also change most of these settings via the built-in web interface.

You can set application configuration either via command-line arguments or environment variables. If both are specified, then the environment variable for the same thing overrides the value from the command-line argument.

Dotenv file

If the working directory contains a "dotenv" file (a file named .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
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=65536 65536

IMAP Worker Count

You can specify a fixed number of threads to start (worker count defaults to 4), or you can use a special value "cpus" that maps to the count of CPU threads.

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

If you want to use multiple EmailEngine instances against the same database, make sure to use unique key prefixes to avoid conflicts.

If you are using a 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
Max POST body size when uploading messages --api.maxBodySize=50M EENGINE_MAX_BODY_SIZE=50M 50M
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.

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. The downside is that events are not guaranteed to be processed in the correct order when having concurrency higher than 1, so grow 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

ENV values from files

Available since v2.22.4

You can set any individual environment variable also from a file. To do this, provide the path to the file that contains the value using an environment key with a _FILE suffix.

If an environment variable is not set, EmailEngine checks if there's a file path variable for that key, and if one is found, then EmailEngine tries to read the value from the referenced file.

In the following example, we provide the value for EENGINE_SECRET from a file at "/path/to/secret.txt"

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