Service: Listmonk - EyevinnOSC/community GitHub Wiki

Listmonk

Listmonk (serviceId knadh-listmonk) is an open-source, self-hosted newsletter and mailing list manager with a high-performance email sending engine. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 10 GiB of storage per instance. License: AGPL-3.0. It depends on PostgreSQL (birme-osc-postgresql).

What it can do

  • Manage multiple mailing lists and subscribers, with segmentation, double opt-in and CSV import.
  • Create campaigns from templates and send them through your own SMTP provider (for example AWS SES, Mailgun, Postmark or any SMTP server); you keep full ownership of subscriber data.
  • Track campaign analytics.
  • Be automated through a REST API.

Creating an instance

  1. Create a PostgreSQL instance (serviceId: "birme-osc-postgresql", options below) with create-service-instance and wait until it is running. Use describe-service-instance for its IP and port. The URL has the form postgres://postgres:<password>@<IP>:<PORT>/postgres.
  2. Store that URL with create-service-secret (serviceId knadh-listmonk), for example name dburl.
  3. Create the instance with create-service-instance, serviceId: "knadh-listmonk":
{ "name": "mynewsletter", "DatabaseUrl": "{{secrets.dburl}}" }

Listmonk runs --install on first start to create its database schema. Wait for it to be running (wait-for-service-ready or get-instance-status) and get the URL with describe-service-instance.

With the OSC CLI:

npx @osaas/cli create birme-osc-postgresql mylistmonkdb \
  -o PostgresPassword="<password>"

npx @osaas/cli create knadh-listmonk mynewsletter \
  -o DatabaseUrl="postgres://postgres:<password>@<IP>:<PORT>/postgres"

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only (^\w+$), at most 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL for Listmonk's data store (subscriber lists, campaigns, templates, application data). The schema is created automatically on first start. Associated with birme-osc-postgresql.

Store DatabaseUrl as a service secret and pass it as {{secrets.NAME}} (whole field value only). Overwriting a secret does not restart a running instance.

PostgreSQL options

birme-osc-postgresql (https://app.osaas.io/dashboard/service/birme-osc-postgresql) is a long-running PostgreSQL instance. License: MIT.

Option Required Type Meaning
name Yes string Name of the instance (^\w+$, at most 20 characters).
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser. Use a secret, for example {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at startup. Defaults to the user name.
PostgresInitDbArgs No string Extra arguments for initdb at cluster initialization (for example encoding or locale).
PostgresInitDbSql No string SQL executed during initialization.

Using the instance

The default credentials are username admin and password listmonk. Change the password immediately after first login (Settings, Users). Then:

  1. Configure SMTP under Settings, SMTP (host, port, username, password) and use "Save and Test" before sending any campaign.
  2. Create a mailing list under Lists and import subscribers from CSV under Subscribers, Import.
  3. Create a campaign under Campaigns, choose a template, write the content, select the list and start it.

Add a subscriber through the REST API:

curl -X POST "https://<instance-url>/api/subscribers" \
  -H "Content-Type: application/json" \
  -u "admin:<password>" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Doe",
    "status": "enabled",
    "lists": [1]
  }'

Limitations

  • The default admin / listmonk credentials are public knowledge; change them straight away.
  • Sending volume is limited only by your SMTP provider's plan.

Resources

⚠️ **GitHub.com Fallback** ⚠️