Listmonk Setup

Listmonk provides the newsletter and mailing-list backend used by FrameWorks forms and account flows. Provisioning starts the container, creates the database tables, and creates the first admin user from GitOps credentials. A few application settings still need operator-owned values.

GitOps Inputs

Set these before provisioning:

# gitops/config/<env>.env
LISTMONK_FRONTEND_URL=https://listmonk.example.com
LISTMONK_ADMIN_USER=admin
LISTMONK_API_USERNAME=frameworks-api
DEFAULT_MAILING_LIST_ID=1

# gitops/secrets/<env>.env, edited via gitops/scripts/sops-env.sh
LISTMONK_ADMIN_PASSWORD=<admin-password>
LISTMONK_API_TOKEN=<api-token-shown-once>

cluster provision maps LISTMONK_FRONTEND_URL into Listmonk’s app.root_url database setting. This is separate from the process environment: Listmonk seeds app.root_url to http://localhost:9000 on first install, and that database setting controls login form actions, public list links, and subscription URLs.

First Login

Open your deployed Listmonk URL and sign in with:

• Username: LISTMONK_ADMIN_USER
• Password: LISTMONK_ADMIN_PASSWORD

If the browser redirects to http://localhost:9000, force-refresh the login page. If it persists, verify settings.app.root_url in the listmonk database.

General Settings

Go to Settings → General and configure:

Setting	Value
Root URL	Your public Listmonk URL, for example https://listmonk.example.com
Site name	Public mailing-list name
From email	A sender address your SMTP account is authorized to use
Notify emails	Operator addresses that should receive Listmonk notifications

From email must match an address allowed by the SMTP provider. For Fastmail, use a mailbox or configured sending alias, for example FrameWorks <[email protected]>.

SMTP

Go to Settings → SMTP and configure at least one enabled SMTP server.

For Fastmail:

Field	Port 465	Port 587
Host	smtp.fastmail.com	smtp.fastmail.com
Port	465	587
Auth protocol	login	login
TLS type	TLS	STARTTLS
Username	Full email address	Full email address
Password	Fastmail app password	Fastmail app password

Do not use cram auth for Fastmail. A 551 5.7.1 Not authorised to send from this header address response means the SMTP login worked, but From email does not match a sendable address on that account.

Lists

Provisioning creates Listmonk’s default lists. FrameWorks services subscribe users to DEFAULT_MAILING_LIST_ID.

• Use a public double-opt-in list for public newsletter signups.
• Keep private/internal lists separate from public forms.
• Update DEFAULT_MAILING_LIST_ID in GitOps when changing which list the FrameWorks forms service targets.

API User

FrameWorks services do not use the admin login for Listmonk API calls. Create a Listmonk user with user type API, give it a dedicated username such as frameworks-api, and assign permissions for subscriber lookup and subscriber updates on the newsletter list. Listmonk displays the API access token only once when the API user is created.

Store the API username in LISTMONK_API_USERNAME and the one-time token in LISTMONK_API_TOKEN. The admin login remains LISTMONK_ADMIN_USER / LISTMONK_ADMIN_PASSWORD and is only used for first-install bootstrap and web console access.