Service: Listmonk - EyevinnOSC/community GitHub Wiki
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).
- 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.
- Create a PostgreSQL instance (
serviceId: "birme-osc-postgresql", options below) withcreate-service-instanceand wait until it is running. Usedescribe-service-instancefor its IP and port. The URL has the formpostgres://postgres:<password>@<IP>:<PORT>/postgres. - Store that URL with
create-service-secret(serviceIdknadh-listmonk), for example namedburl. - 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"| 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.
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. |
The default credentials are username admin and password listmonk. Change the password immediately after first login (Settings, Users). Then:
- Configure SMTP under Settings, SMTP (host, port, username, password) and use "Save and Test" before sending any campaign.
- Create a mailing list under Lists and import subscribers from CSV under Subscribers, Import.
- 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]
}'- The default
admin/listmonkcredentials are public knowledge; change them straight away. - Sending volume is limited only by your SMTP provider's plan.