Skip to main content

​
Configuration File

listmonk uses TOML configuration files for low-level settings. Most settings can also be managed through the Settings dashboard in the admin UI.

​
Generating config.toml

To generate a new sample configuration file: 
listmonk --new-config
The default location is config.toml in the current directory.

​
Multiple Config Files

You can load multiple TOML files that will be merged in order: 
listmonk --config config.toml --config custom.toml

​
Environment Variables

All configuration variables can be provided as environment variables prefixed with LISTMONK_ and periods replaced by __ (double underscore).
To run listmonk purely with environment variables, pass an empty config flag: --config=""

​
Environment Variable Examples

Environment VariableExample ValueDescription
LISTMONK_app__address"0.0.0.0:9000"Server address and port
LISTMONK_db__host"localhost"Database host
LISTMONK_db__port5432Database port
LISTMONK_db__user"listmonk"Database user
LISTMONK_db__password"listmonk"Database password
LISTMONK_db__database"listmonk"Database name
LISTMONK_db__ssl_mode"disable"Database SSL mode

​
Application Settings

​
Server Address

​
app.address
string
default:"localhost:9000"
Interface and port where the app runs its webserver.
  • localhost:9000 - Only listens to connections from the current machine
  • 0.0.0.0:9000 - Listens on all interfaces
  • Port 80 requires running with elevated permissions
[app]
address = "0.0.0.0:9000"

​
URL Configuration

Configured through the Settings UI:
​
app.root_url
string
default:"http://localhost:9000"
Root URL of the listmonk installation. Used for generating public URLs for unsubscribe links, tracking pixels, etc.
​
app.logo_url
string
default:""
URL to a logo image displayed in the admin interface and public pages.
​
app.favicon_url
string
default:""
URL to a favicon displayed in the admin interface.

​
Database Configuration

listmonk requires PostgreSQL version 12 or higher.
​
db.host
string
default:"localhost"
PostgreSQL server hostname or IP address.
​
db.port
integer
default:"5432"
PostgreSQL server port.
​
db.user
string
default:"listmonk"
Database user name.
​
db.password
string
default:"listmonk"
Database password.
​
db.database
string
default:"listmonk"
Database name. This database must be created in PostgreSQL before running listmonk.
​
db.ssl_mode
string
default:"disable"
SSL mode for database connection.Options: disable, require, verify-ca, verify-full
​
db.max_open
integer
default:"25"
Maximum number of open database connections in the pool.
​
db.max_idle
integer
default:"25"
Maximum number of idle database connections in the pool.
​
db.max_lifetime
duration
default:"300s"
Maximum lifetime of a database connection.
​
db.params
string
default:""
Optional space-separated PostgreSQL DSN parameters.Example: "application_name=listmonk gssencmode=disable"

​
Database Configuration Example

[db]
host = "localhost"
port = 5432
user = "listmonk"
password = "listmonk"
database = "listmonk"
ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"
params = ""

​
Performance Settings

These settings are configured through the Settings UI under Settings → Performance.
​
app.batch_size
integer
default:"1000"
Number of subscribers fetched from the database in a single cycle (~5 seconds) when a campaign is running.
Increasing batch size uses more memory but reduces database round trips. Useful for large lists with millions of subscribers.
​
app.concurrency
integer
default:"10"
Maximum number of concurrent workers that send messages.
​
app.message_rate
integer
default:"10"
Maximum number of messages to send per second per worker.
​
app.max_send_errors
integer
default:"1000"
Maximum number of send errors before a campaign is paused.
​
app.message_sliding_window
boolean
default:"false"
Enable sliding window rate limiting instead of per-second rate limiting.
​
app.message_sliding_window_duration
duration
default:"1h"
Duration of the sliding window for rate limiting.
​
app.message_sliding_window_rate
integer
default:"10000"
Maximum number of messages to send within the sliding window duration.

​
Slow Query Caching

​
app.cache_slow_queries
boolean
default:"false"
Enable caching of slow queries for better dashboard performance.
When enabled, aggregate numbers and stats will not be real-time.
​
app.cache_slow_queries_interval
string
default:"0 3 * * *"
Cron interval for refreshing cached queries (default: 3 AM daily).

​
Notification Settings

​
app.from_email
string
default:"listmonk <[email protected]>"
Default “From” email address for campaigns and system notifications.
​
app.notify_emails
array
default:"[]"
Array of email addresses to receive system notifications (import completion, errors, etc.).Example: ["[email protected]", "[email protected]"]

​
Public Features

​
app.enable_public_subscription_page
boolean
default:"true"
Enable the public subscription management page where subscribers can manage their subscriptions.
​
app.enable_public_archive
boolean
default:"true"
Enable the public campaign archive page.
​
app.enable_public_archive_rss_content
boolean
default:"true"
Include full campaign content in the public archive RSS feed.

​
Internationalization

​
app.lang
string
default:"en"
Default language for the admin interface and public pages.Supported languages are determined by available translation files in the i18n directory.

​
Additional Settings

​
app.send_optin_confirmation
boolean
default:"true"
Automatically send opt-in confirmation emails to new subscribers.
​
app.check_updates
boolean
default:"true"
Check for new listmonk versions on startup.

​
Reloading Configuration

Most settings can be changed through the Settings UI and take effect immediately. Changes to the TOML configuration file or environment variables require restarting listmonk.When you update settings through the admin UI, listmonk sends a SIGHUP signal to reload the configuration.
# Send reload signal manually
kill -HUP $(pgrep listmonk)
Database settings and the server address require a full restart and cannot be hot-reloaded.

​
Advanced Configuration

​
Custom Static and i18n Directories

You can override the default static files and internationalization files: 
listmonk --static-dir=/path/to/static --i18n-dir=/path/to/i18n

​
Passive Mode

Run listmonk in passive mode where campaigns are not processed: 
listmonk --passive
This is useful for running multiple listmonk instances where only one instance processes campaigns.

​
Docker Configuration

When running with Docker, you can mount a custom config file: 
services:
  app:
    image: listmonk/listmonk:latest
    volumes:
      - ./config.toml:/listmonk/config.toml
    command: [
      sh, -c,
      "./listmonk --config /listmonk/config.toml"
    ]

Build docs developers (and LLMs) love

Get started for freeTalk to us