Skip to main content

Prepared Settings

Prepared configuration allows you to pre-configure EmailEngine settings, access tokens, and license keys before the application starts. This is essential for automated deployments, CI/CD pipelines, and containerized environments where manual configuration is impractical.

Overview​

EmailEngine supports three types of prepared configuration:

  1. Prepared Settings - Runtime configuration (webhooks, OAuth2, etc.)
  2. Prepared Access Tokens - API authentication tokens
  3. Prepared License Keys - License activation

All prepared configuration is applied on every application startup. This means settings will be overwritten each time EmailEngine starts, ensuring your environment configuration always takes precedence.

Use Cases​

Automated Deployments:

  • Docker/Kubernetes deployments
  • Infrastructure as Code (Terraform, Ansible)
  • CI/CD pipelines

Testing:

  • End-to-end automated testing
  • Integration test environments
  • Staging environment setup

Multi-Environment Setup:

  • Development, staging, production configs
  • Multi-tenant deployments
  • Rapid environment provisioning

Prepared Settings​

Pre-configure runtime settings that would normally be set via the Settings API or web interface.

What Can Be Pre-Configured​

Any setting available via the /v1/settings API endpoint:

  • Webhook URLs and event filters
  • SMTP server configuration (built-in SMTP server)
  • Service URL and base URLs
  • Tracking settings (clicks, opens)
  • Logging configuration
  • Proxy settings
  • IMAP proxy configuration
  • UI branding and locale settings

Configuration Methods​

Set the EENGINE_SETTINGS environment variable with a JSON string:

export EENGINE_SETTINGS='{"webhooks": "https://webhook.site/abc123","webhookEvents":["messageNew"]}'
emailengine

Examples​

Basic webhook configuration:

EENGINE_SETTINGS='{
  "webhooks": "https://your-app.com/webhook",
  "webhookEvents": ["messageNew", "messageSent"]
}'

Complete configuration:

EENGINE_SETTINGS='{
  "webhooks": "https://your-app.com/webhook",
  "webhookEvents": [
    "messageNew",
    "messageDeleted",
    "messageSent",
    "messageDeliveryError"
  ],
  "notifyText": "New email notification",
  "notifyTextSize": 100,
  "serviceUrl": "https://emailengine.example.com"
}'

SMTP server and tracking:

EENGINE_SETTINGS='{
  "smtpServerEnabled": true,
  "smtpServerPort": 2525,
  "smtpServerHost": "0.0.0.0",
  "smtpServerAuthEnabled": true,
  "trackClicks": true,
  "trackOpens": true
}'
OAuth2 Configuration

OAuth2 provider credentials (Gmail, Outlook) should be configured using the OAuth2 Applications API (/v1/oauth2) rather than the settings endpoint. The legacy settings like gmailClientId are deprecated.

Validation​

Settings are validated on startup. If validation fails, the application won't start:

Error: Invalid settings configuration
  - webhooks: must be a valid URL
  - webhookEvents: must be an array

Check your JSON syntax and setting values if you encounter errors.

Updating Prepared Settings​

Prepared settings are applied on every startup, overwriting existing values. To update:

  1. Update the EENGINE_SETTINGS environment variable and restart EmailEngine
  2. Or use the Settings API for runtime changes (will be overwritten on next restart if also defined in EENGINE_SETTINGS)

Update settings via API:

# Update specific setting
curl -X POST http://localhost:3000/v1/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": "https://new-webhook-url.com/webhook",
    "webhookEvents": ["messageNew", "messageSent"]
  }'

# Clear specific setting by setting to null
curl -X POST http://localhost:3000/v1/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhooks": null}'

See Also​