Configuration Reference

Comprehensive reference for all EmailEngine configuration options.

Configuration Methods

EmailEngine can be configured via:

1. Environment variables (highest priority)
2. Command-line arguments
3. Configuration file (TOML format)

Configuration Types

Startup Configuration

Loaded at startup. Requires restart to apply changes.

• HTTP port, workers, Redis connection
• Secret for encryption
• License key
• Logging settings
• TLS settings

Runtime Configuration

Can be updated via Settings API or web interface without restart.

• Service URL
• Webhook URLs and settings
• Email sending limits
• SMTP gateways
• Proxy settings
• OAuth2 applications (configured via API, not environment variables)

Core Settings

Server Configuration

Port

Environment: EENGINE_PORT Command line: --api.port=3000 Config file: api.port Default: 3000

HTTP port for the web interface and API.

# Environment
export EENGINE_PORT=8080

# Command line
emailengine --api.port=8080

# Config file (config.toml)
[api]
port = 8080

Host

Environment: EENGINE_HOST Command line: --api.host=0.0.0.0 Config file: api.host Default: 127.0.0.1

IP address to bind to. Use 0.0.0.0 to listen on all interfaces.

EENGINE_HOST=0.0.0.0

Security

Only use 0.0.0.0 if behind a reverse proxy. Otherwise, bind to 127.0.0.1.

Service URL

Runtime config: Settings API or web interface Setting name: serviceUrl

Base URL for generating links (OAuth redirects, webhook URLs, authentication forms). This is a runtime setting, not an environment variable.

# Configure via API
curl -X POST https://emailengine.example.com/v1/settings \
  -H "Authorization: Bearer TOKEN" \
  -d '{"serviceUrl": "https://emailengine.example.com"}'

# Or via EENGINE_SETTINGS environment variable at startup
EENGINE_SETTINGS='{"serviceUrl":"https://emailengine.example.com"}'

Workers

IMAP Worker Threads

Environment: EENGINE_WORKERS Command line: --workers.imap=4 Config file: workers.imap Default: 4

Number of IMAP worker threads for processing accounts.

EENGINE_WORKERS=8

Recommendation: Set to number of CPU cores for optimal performance.

# Auto-detect CPU cores (Linux)
EENGINE_WORKERS=$(nproc)

Webhook Workers

Environment: EENGINE_WORKERS_WEBHOOKS Config file: workers.webhooks Default: 1

Number of webhook delivery worker threads.

Submit Workers

Environment: EENGINE_WORKERS_SUBMIT Config file: workers.submit Default: 1

Number of email submission worker threads.

Redis Configuration

Connection URL

Environment: EENGINE_REDIS Command line: --dbs.redis=redis://localhost:6379/8 Config file: dbs.redis Default: redis://127.0.0.1:6379/8

Redis connection URL. The default database number is 8.

# Default (database 8)
EENGINE_REDIS=redis://localhost:6379/8

# With password
EENGINE_REDIS=redis://:password@localhost:6379/8

# With username and password
EENGINE_REDIS=redis://username:password@localhost:6379/8

# With different database number
EENGINE_REDIS=redis://localhost:6379/5

# TLS connection
EENGINE_REDIS=rediss://localhost:6379/8

# IPv6 only
EENGINE_REDIS=redis://localhost:6379/8?family=6

Redis Key Prefix

Environment: EENGINE_REDIS_PREFIX Default: Empty

Prefix for all Redis keys. Useful when sharing a Redis instance.

EENGINE_REDIS_PREFIX=ee1:

Security

Secret

Environment: EENGINE_SECRET Command line: --service.secret=... Config file: service.secret Required: Yes (for production)

Secret used for encrypting session tokens AND account credentials (passwords, OAuth tokens). This is a single secret that serves both purposes.

Generate and save:

# Generate a 64-character hex secret
openssl rand -hex 32

# Add to environment or .env file
EENGINE_SECRET=your-generated-secret-here

Required for Production

EmailEngine will start without this secret in development mode, but all sensitive data will be stored unencrypted. Always set a strong secret in production.

Secret Management

• Keep a secure backup of your secret
• If lost, encrypted credentials cannot be recovered
• Changing the secret requires re-encrypting existing data using the encrypt command

Re-encrypting data after secret change:

emailengine encrypt --dbs.redis="redis://url" --service.secret="new-secret" --decrypt="old-secret"

Logging

Log Level

Environment: EENGINE_LOG_LEVEL Command line: --log.level=info Config file: log.level Default: trace

Logging verbosity level.

Levels: silent, fatal, error, warn, info, debug, trace

# Production
EENGINE_LOG_LEVEL=info

# Development
EENGINE_LOG_LEVEL=trace

# Minimal
EENGINE_LOG_LEVEL=warn

Log Raw

Environment: EENGINE_LOG_RAW Config file: log.raw Default: false

Log raw IMAP/SMTP protocol traffic and OAuth2 API requests.

EENGINE_LOG_RAW=true

Security Warning - Contains Unmasked Credentials

When enabled, logs contain unmasked sensitive data:

• IMAP/SMTP traffic: Base64-encoded protocol data includes plaintext passwords in AUTH commands
• OAuth2 API requests: Access tokens, refresh tokens, and client secrets are logged without filtering
• All credentials are visible: Nothing is redacted or masked

Never enable in production. Use only for local debugging, and delete logs immediately after troubleshooting.

Performance

Enabling this creates very large log files due to the volume of protocol data.

OAuth2 Configuration

OAuth2 applications (Gmail, Outlook, Mail.ru) are configured via the Settings API or web interface, not environment variables.

Configuring OAuth2 via API

Endpoint: POST /v1/oauth2 - API Reference

Supported providers:

• gmail - Gmail with 3-legged OAuth2 (user consent)
• gmailService - Gmail with service account (2-legged OAuth2)
• outlook - Microsoft 365 / Outlook
• mailRu - Mail.ru

# Create Gmail OAuth2 application (3-legged OAuth2)
curl -X POST https://emailengine.example.com/v1/oauth2 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail",
    "provider": "gmail",
    "clientId": "123456789.apps.googleusercontent.com",
    "clientSecret": "GOCSPX-xxxxxxxxxxxxx",
    "baseScopes": "imap",
    "enabled": true
  }'

# Create Outlook OAuth2 application
curl -X POST https://emailengine.example.com/v1/oauth2 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outlook",
    "provider": "outlook",
    "clientId": "12345678-1234-1234-1234-123456789012",
    "clientSecret": "your-azure-secret",
    "authority": "common",
    "enabled": true
  }'

# Create Gmail Service Account application (2-legged OAuth2)
curl -X POST https://emailengine.example.com/v1/oauth2 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail Service Account",
    "provider": "gmailService",
    "serviceClient": "123456789012345678901",
    "serviceClientEmail": "myapp@project-123.iam.gserviceaccount.com",
    "serviceKey": "-----BEGIN PRIVATE KEY-----\nMIIEv...\n-----END PRIVATE KEY-----",
    "enabled": true
  }'

Key fields:

• name - Display name for the application
• provider - One of: gmail, gmailService, outlook, mailRu
• clientId / clientSecret - OAuth2 credentials (for 3-legged OAuth2)
• serviceClient / serviceClientEmail / serviceKey - Service account credentials (for Gmail service accounts)
• authority - Microsoft tenant: common, organizations, consumers, or tenant ID
• baseScopes - Connection type: imap, api, or pubsub
• enabled - Whether the application is active

Configuring OAuth2 via Web Interface

1. Navigate to Configuration > OAuth2
2. Click Register new application
3. Select provider (Gmail, Outlook, Gmail Service Account, or Mail.ru)
4. Enter your OAuth2 credentials
5. Click Register application

Related API Endpoints

• List OAuth2 applications - GET /v1/oauth2
• Register OAuth2 application - POST /v1/oauth2
• Get OAuth2 application - GET /v1/oauth2/{app}
• Update OAuth2 application - PUT /v1/oauth2/{app}
• Delete OAuth2 application - DELETE /v1/oauth2/{app}

For detailed OAuth2 setup instructions, see:

• Gmail OAuth2 Setup
• Outlook OAuth2 Setup

Performance Tuning

Command Timeout

Environment: EENGINE_TIMEOUT Command line: --service.commandTimeout=10000 Config file: service.commandTimeout Default: 10000 (10 seconds)

Timeout for IMAP commands in milliseconds.

EENGINE_TIMEOUT=30000

Fetch Batch Size

Environment: EENGINE_FETCH_BATCH_SIZE Command line: --service.fetchBatchSize=1000 Config file: service.fetchBatchSize Default: 1000

Number of messages to fetch per batch during synchronization.

EENGINE_FETCH_BATCH_SIZE=500

Lower values: Slower sync, less memory usage Higher values: Faster sync, more memory usage

Download Chunk Size

Environment: EENGINE_CHUNK_SIZE Default: 1000000 (1 MB)

Chunk size for streaming large message downloads.

EENGINE_CHUNK_SIZE=2000000

URL Fetch Timeout

Environment: EENGINE_FETCH_TIMEOUT Default: 90000 (90 seconds)

Timeout for fetching external URLs (attachments, templates) in milliseconds.

EENGINE_FETCH_TIMEOUT=120000

Connection Setup Delay

Environment: EENGINE_CONNECTION_SETUP_DELAY Default: 0

Delay in milliseconds between setting up account connections. Useful for rate limiting during startup.

EENGINE_CONNECTION_SETUP_DELAY=100

API Server Settings

Max Body Size

Environment: EENGINE_MAX_BODY_SIZE Default: 50MB

Maximum request body size for API requests.

EENGINE_MAX_BODY_SIZE=100MB

Max Payload Timeout

Environment: EENGINE_MAX_PAYLOAD_TIMEOUT Default: 10000 (10 seconds)

Timeout for receiving request payloads.

EENGINE_MAX_PAYLOAD_TIMEOUT=30000

CORS Configuration

CORS Origin

Environment: EENGINE_CORS_ORIGIN Default: None (CORS disabled)

Allowed CORS origins. Set to * for all origins or specific domain.

EENGINE_CORS_ORIGIN=https://your-app.com

CORS Max Age

Environment: EENGINE_CORS_MAX_AGE Default: 60

CORS preflight cache duration in seconds.

EENGINE_CORS_MAX_AGE=3600

API Authentication

Require API Authentication

Environment: EENGINE_REQUIRE_API_AUTH Default: true

Whether API requests require authentication tokens.

# Disable for development only
EENGINE_REQUIRE_API_AUTH=false

Security

Never disable API authentication in production.

TLS Configuration

Enable API TLS

Environment: EENGINE_API_TLS Default: false

Enable TLS for the API server.

EENGINE_API_TLS=true

TLS Minimum Version

Environment: EENGINE_TLS_MIN_VERSION Default: TLSv1

Minimum TLS version to accept.

EENGINE_TLS_MIN_VERSION=TLSv1.2

TLS Ciphers

Environment: EENGINE_TLS_CIPHERS Default: DEFAULT@SECLEVEL=0

TLS cipher suites to use.

EENGINE_TLS_CIPHERS=ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384

TLS Min DH Size

Environment: EENGINE_TLS_MIN_DH_SIZE Default: 1024

Minimum DH parameter size.

EENGINE_TLS_MIN_DH_SIZE=2048

Reverse Proxy Mode

Environment: EENGINE_API_PROXY Default: false

When enabled, client IP addresses are read from the X-Forwarded-For header instead of the socket connection. Enable this when running EmailEngine behind a reverse proxy (Nginx, HAProxy, load balancer, etc.).

EENGINE_API_PROXY=true

Security

Only enable this if EmailEngine is behind a trusted reverse proxy. Otherwise, clients could spoof their IP address by setting the X-Forwarded-For header.

Webhooks

Webhook settings are configured via the Settings API or web interface.

Configure Webhooks via API

# Set webhook URL and events
curl -X POST https://emailengine.example.com/v1/settings \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": "https://your-app.com/webhooks",
    "webhooksEnabled": true,
    "webhookEvents": ["messageNew", "messageDeleted", "accountAuthenticationError"]
  }'

Pre-configure Webhooks at Startup

Use EENGINE_SETTINGS to configure webhooks at startup:

EENGINE_SETTINGS='{"webhooks":"https://your-app.com/webhooks","webhooksEnabled":true,"webhookEvents":["*"]}'

Monitoring

Metrics Endpoint

The Prometheus metrics endpoint is available at /metrics on the main API server. It requires authentication with a token that has the metrics scope.

Endpoint: http://localhost:3000/metrics

Authentication: Requires API token with metrics scope (or * for full access)

# Create a metrics-only token via CLI
emailengine tokens issue -d "Prometheus" -s "metrics"

# Or create via API
curl -X POST https://emailengine.example.com/v1/token \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d '{"description": "Prometheus", "scopes": ["metrics"]}'

# Access metrics
curl -H "Authorization: Bearer METRICS_TOKEN" http://localhost:3000/metrics

Health Check

Endpoint: /health Always enabled, no authentication required

Returns health status.

curl http://localhost:3000/health

License

License Key

Environment: EENGINE_PREPARED_LICENSE Command line: --preparedLicense=... Config file: preparedLicense Default: 14-day trial

Production license key.

# From file
EENGINE_PREPARED_LICENSE="$(cat /path/to/license.txt)"

# Inline (PEM format)
EENGINE_PREPARED_LICENSE="-----BEGIN LICENSE-----
Application: EmailEngine
Licensed to: Your Company

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-----END LICENSE-----"

Trial Mode

Without a license key, EmailEngine runs in 14-day trial mode with full functionality. Activate trial via the dashboard.

Pre-configured Settings

Prepared Settings

Environment: EENGINE_SETTINGS

JSON string of runtime settings to apply at startup.

EENGINE_SETTINGS='{"serviceUrl":"https://emailengine.example.com","webhooks":"https://your-app.com/webhooks","webhooksEnabled":true}'

Prepared API Token

Environment: EENGINE_PREPARED_TOKEN Command line: --preparedToken=... Config file: preparedToken

Pre-configure an API access token at startup. This accepts an exported token hash, not the actual access token value.

Workflow:

1. Generate a token: emailengine tokens issue -d "API Token" -s "*"
2. Export the token: emailengine tokens export -t <token-value>
3. Use the exported string (not the original token) as EENGINE_PREPARED_TOKEN

# The value is an exported token hash from "emailengine tokens export"
EENGINE_PREPARED_TOKEN=hKJpZNlAMzAxZThjNTFhZjgxM2Q3MzUxNTYzYTFlM2I1NjVkYmEzZWJjMzk4ZjI4OWZjNjgzN...

For complete token management workflow, see Prepared Tokens.

Prepared Admin Password

Environment: EENGINE_PREPARED_PASSWORD Command line: --preparedPassword=... Config file: preparedPassword

Pre-configure the admin password at startup. This accepts a base64url-encoded password hash, not a plain password.

Workflow:

1. Generate a password hash: emailengine password -p "your-password" --hash
2. Use the returned hash as EENGINE_PREPARED_PASSWORD

# Generate hash
emailengine password -p "my-secure-password" --hash
# Output: JHBia2RmMi1zaGE1MTIkaTEwMDAwMCRhYmNkZWYxMjM0NTY3ODkw...

# Use the hash (not the plain password)
EENGINE_PREPARED_PASSWORD=JHBia2RmMi1zaGE1MTIkaTEwMDAwMCRhYmNkZWYxMjM0NTY3ODkw...

Disable Setup Warnings

Environment: EENGINE_DISABLE_SETUP_WARNINGS Default: false

Disable admin password setup warnings.

EENGINE_DISABLE_SETUP_WARNINGS=true

Admin Access Control

Admin Access Addresses

Environment: EENGINE_ADMIN_ACCESS_ADDRESSES Default: All addresses

Comma-separated list of IP addresses allowed to access admin interface.

EENGINE_ADMIN_ACCESS_ADDRESSES=127.0.0.1,10.0.0.0/8

Disable Message Browser

Environment: EENGINE_DISABLE_MESSAGE_BROWSER Default: false

Disable the message browser in the admin interface.

EENGINE_DISABLE_MESSAGE_BROWSER=true

IMAP Settings

Disable IMAP Compression

Environment: EENGINE_DISABLE_COMPRESSION Default: false

Disable IMAP COMPRESS extension.

EENGINE_DISABLE_COMPRESSION=true

IMAP Socket Timeout

Environment: EENGINE_IMAP_SOCKET_TIMEOUT Default: None (system default)

Socket timeout for IMAP connections in milliseconds.

EENGINE_IMAP_SOCKET_TIMEOUT=300000

Max IMAP Auth Failure Time

Environment: EENGINE_MAX_IMAP_AUTH_FAILURE_TIME Default: 3d (3 days)

Time before disabling IMAP connections after repeated auth failures.

EENGINE_MAX_IMAP_AUTH_FAILURE_TIME=1d

Queue Settings

Submit Queue Concurrency

Environment: EENGINE_SUBMIT_QC Default: 1

Concurrency for email submission queue.

EENGINE_SUBMIT_QC=4

Submit Delay

Environment: EENGINE_SUBMIT_DELAY Default: None

Delay between email submissions in milliseconds.

EENGINE_SUBMIT_DELAY=1000

Notify Queue Concurrency

Environment: EENGINE_NOTIFY_QC Default: 1

Concurrency for notification/webhook queue.

EENGINE_NOTIFY_QC=4

Queue Cleanup Time

Environment: EENGINE_QUEUE_REMOVE_AFTER Default: 0 (no cleanup)

Time to keep completed jobs before cleanup.

EENGINE_QUEUE_REMOVE_AFTER=86400000

SMTP Proxy Server

EmailEngine can run an SMTP proxy server that accepts SMTP connections and routes them through configured accounts.

Enable SMTP Proxy

Environment: EENGINE_SMTP_ENABLED Default: false

EENGINE_SMTP_ENABLED=true

SMTP Proxy Port

Environment: EENGINE_SMTP_PORT Default: 2525

EENGINE_SMTP_PORT=587

SMTP Proxy Host

Environment: EENGINE_SMTP_HOST Default: 127.0.0.1

EENGINE_SMTP_HOST=0.0.0.0

SMTP Proxy Secret

Environment: EENGINE_SMTP_SECRET Default: Empty

Password for SMTP proxy authentication. If not set, API access tokens with the smtp scope can be used for authentication instead.

EENGINE_SMTP_SECRET=your-smtp-password

SMTP PROXY Protocol

Environment: EENGINE_SMTP_PROXY Default: false

Enable PROXY protocol for SMTP proxy server.

EENGINE_SMTP_PROXY=true

SMTP Max Message Size

Environment: EENGINE_MAX_SMTP_MESSAGE_SIZE Default: 25MB

Maximum message size the SMTP proxy server accepts for delivery.

EENGINE_MAX_SMTP_MESSAGE_SIZE=50MB

IMAP Proxy Server

EmailEngine can run an IMAP proxy server that accepts IMAP connections and routes them through configured accounts.

Enable IMAP Proxy

Environment: EENGINE_IMAP_PROXY_ENABLED Default: false

EENGINE_IMAP_PROXY_ENABLED=true

IMAP Proxy Port

Environment: EENGINE_IMAP_PROXY_PORT Default: 2993

EENGINE_IMAP_PROXY_PORT=993

IMAP Proxy Host

Environment: EENGINE_IMAP_PROXY_HOST Default: 127.0.0.1

EENGINE_IMAP_PROXY_HOST=0.0.0.0

IMAP Proxy Secret

Environment: EENGINE_IMAP_PROXY_SECRET Default: Empty

Password for IMAP proxy authentication. If not set, API access tokens with the imap-proxy scope can be used for authentication instead.

EENGINE_IMAP_PROXY_SECRET=your-imap-password

IMAP PROXY Protocol

Environment: EENGINE_IMAP_PROXY_PROXY Default: false

Enable PROXY protocol for IMAP proxy.

EENGINE_IMAP_PROXY_PROXY=true

OAuth Token Access

Enable OAuth Tokens API

Environment: EENGINE_ENABLE_OAUTH_TOKENS_API Default: false

Allow retrieving raw OAuth tokens via API.

EENGINE_ENABLE_OAUTH_TOKENS_API=true

Security

Only enable if you need to access raw OAuth tokens. This exposes sensitive credentials.

Environment Variable Reference

Quick Reference Table

Environment Variable	Default	Description
EENGINE_PORT	3000	HTTP port
EENGINE_HOST	127.0.0.1	Bind address
EENGINE_REDIS	redis://127.0.0.1:6379/8	Redis URL
EENGINE_SECRET	None	Encryption secret (required for production)
EENGINE_WORKERS	4	IMAP worker threads
EENGINE_LOG_LEVEL	trace	Log level
EENGINE_TIMEOUT	10000	Command timeout (ms)
EENGINE_FETCH_BATCH_SIZE	1000	Messages per sync batch
EENGINE_PREPARED_LICENSE	None	License key
EENGINE_SETTINGS	None	Pre-configured settings JSON
EENGINE_PREPARED_TOKEN	None	Exported token hash (not raw token)
EENGINE_PREPARED_PASSWORD	None	Password hash (not plain password)
EENGINE_REQUIRE_API_AUTH	true	Require API authentication
EENGINE_CORS_ORIGIN	None	CORS allowed origin
EENGINE_SMTP_ENABLED	false	Enable SMTP proxy
EENGINE_IMAP_PROXY_ENABLED	false	Enable IMAP proxy

Configuration File Example

Complete config.toml

# EmailEngine Configuration File
# Place in working directory or specify with --config

[service]
# Encryption secret - required for production
# Generate with: openssl rand -hex 32
secret = "your-64-character-hex-secret-here"

# Command timeout in milliseconds
commandTimeout = 10000

# Messages per sync batch
fetchBatchSize = 1000

[api]
port = 3000
host = "127.0.0.1"

[dbs]
redis = "redis://localhost:6379/8"

[workers]
imap = 4
webhooks = 1
submit = 1

[log]
level = "info"
# raw = true  # Enable for debugging only

Using TOML Config

TOML is the native configuration format for EmailEngine. Use --config=/path/to/config.toml to specify a custom config file location.

Priority Order

When the same setting is configured in multiple ways:

1. Environment variables (highest priority)
2. Command-line arguments
3. Configuration file (lowest priority)

Example:

# Config file: api.port = 3000
# Command line: --api.port=4000
# Environment: EENGINE_PORT=5000

# Result: Port 5000 (environment wins)

See Also

• Environment Variables Guide
• Redis Configuration
• Security Best Practices
• Docker Deployment