Update the config related docs to be clearer on the exact valid environment variables.

[hayone1]

I just spent almost 2 days trying to configure listmonk to work with environment variables beyond the "LISTMONK_db" config.

The first big challenge was that the docs seem to suggests that environment variables can be used in the same way as toml and is not explicit about stating that the "Example:" given also represent the only keys supported.

As I began to research, certain issues led me down a wrong path, eg. this issue solution from 2020 clearly shows smtp configuration from environment variables—This one too.
Then we have this code that seems like it nicely merges environment variables with the toml config.

Another issue is that I couldn't find a list of the toml supported values. I had to locate it from this issue and this code. Digging a little more, there is also this.

AI was also leading me on and I persisted in my approach until I found this 2025 issue did I give up. Unfortunately, Github does not recommend this issue when you search even with the relevant keywords. Even if you go very specific, eg. you search for "LISTMONK_smtp__". Github just comes up with an empty result

To prevent hundreds like me from going through this, it would be great to be explicit in the docs or to actually support it.

It would be nice to configure something like the below.

LISTMONK_upload__provider
LISTMONK_upload__s3__aws_access_key_id
LISTMONK_upload__s3__aws_secret_access_key
LISTMONK_upload__s3__bucket
LISTMONK_upload__s3__bucket_path
LISTMONK_upload__s3__bucket_type
LISTMONK_upload__s3__url

Thanks so much for an awesome app

[hayone1]

Update.

I have not switched to toml and the logs show a successful reading of the DB data on startup but nothing in the settings appear to have changed. It seems that only the database section was used. I'm either doing something wrong or the only way to currently make configurations is through the UI. (Note that the env variables are substituted before the app is started so it starts with plain toml)

[db]                                                                                   
host = "postgres-rw"                                                                     
port = 5432                                                                            
user = "listmonk-user"                                                                      
password = "${COMMON_DB_PASS}"                                                          
database = "listmonk-db"                                                                  
ssl_mode = "disable"                                                                   
max_open = 50                                                                          
max_idle = 10

[app]
address = "0.0.0.0:9000"
site_name = "APP"
root_url = "https://listmonk.${DOMAIN_NAME}"
from_email = "myapp <myapp@gmail.com>"
notify_emails = ["info@myapp.global", "secondemail@gmail.com"]
concurrency = 2
message_rate = 5
message_sliding_window = true
message_sliding_window_rate = 500
message_sliding_window_duration = "24h"

[smtp]                                                                                 
  [smtp.myappglobal]
    enabled = true
    host    = "stalwart-mail-server"
    port    = 587
    auth_protocol    = "login"
    username    = "${STALWART_MAIN_EMAIL}"
    password    = "${STALWART_MAIN_EMAIL_PASSWORD}"
    tls_type    = "STARTTLS"
    tls_skip_verify    = true
  [smtp.gmail]
    enabled = true
    host    = "smtp.gmail.com"
    port    = 465
    auth_protocol    = "login"
    username    = "${GMAIL_MAIN_EMAIL}"
    password    = "${GMAIL_MAIN_EMAIL_PASSWORD}"
    tls_type    = "TLS"

[upload]
provider = "s3" 
  [upload.s3]
    aws_access_key_id = "${OBJECT_STORAGE_ACCESS_KEY_ID}"
    aws_secret_access_key = "${OBJECT_STORAGE_ACCESS_SECRET_KEY}"
    bucket = "myapp-campaign-bucket"
    bucket_path = "/media"

[security.oidc]
enabled = true
provider_url = "https://mailserver.${DOMAIN_NAME}"
provider_name = "Email"
client_id = "${LISTMONK_OAUTH_CLIENT_ID}"
client_secret = "${LISTMONK_OAUTH_CLIENT_SECRET}"
auto_create_users = true

[knadh]

Hi @hayone1. The documentation clearly says that only the variables in config.toml are supported as environment variables. DB settings are not supported. Example in the section heading, we can change to Supported variables to avoid any confusion.

---