Getting Started

Listmonk is an open-source, self-hosted newsletter and mailing list manager with a high-performance email sending engine. It supports multiple mailing lists, segmentation, campaign analytics, double opt-in, templating, and a REST API. Available as an open web service in Eyevinn Open Source Cloud, Listmonk gives you full ownership of your subscriber data and no sending limits beyond your SMTP provider's plan.

Prerequisites

  • If you have not already done so, sign up for an Eyevinn OSC account
  • An SMTP provider to send emails (e.g. AWS SES, Mailgun, Postmark, or any SMTP server)

Step 1: Create a PostgreSQL database

Listmonk requires a PostgreSQL database to store subscribers, campaigns, and analytics. Navigate to the PostgreSQL service in the Eyevinn OSC web console. Click on "Create psql-db" and fill in:

  • Name: a name for your database instance (alphanumeric only)
  • Password: a strong password for the postgres user

Once the instance is running, note the IP and port. The connection URL will be:

postgres://postgres:<password>@<IP>:<PORT>/postgres

Step 2: Store the database URL as a secret

Navigate to the Listmonk service in the Eyevinn OSC web console. Go to the tab "Service Secrets" and click "New Secret".

Create a secret named dburl containing the PostgreSQL connection URL from Step 1.

Step 3: Create the Listmonk instance

Go to the tab "My listmonk" and click "Create listmonk". Fill in:

  • Name: a name for your instance (alphanumeric only)
  • DatabaseUrl: {{secrets.dburl}}

Listmonk automatically runs --install on first start to create its database schema.

Click the instance card when the status is green and "running" to open the Listmonk dashboard.

Step 4: Log in and configure SMTP

The default credentials are:

  • Username: admin
  • Password: listmonk

After logging in, navigate to Settings → SMTP to configure your email sending provider. Enter your SMTP host, port, username, and password. Click "Save and Test" to verify the connection before sending any campaigns.

Change your admin password immediately after first login under Settings → Users.

Step 5: Import subscribers and create your first campaign

  1. Go to Lists and create a mailing list (e.g. "Newsletter")
  2. Go to Subscribers → Import to upload a CSV file with subscriber emails
  3. Go to Campaigns → New Campaign, choose a template, write your content, and select the list
  4. Click Start to begin sending

Usage example

Connect to the Listmonk API from your application to add subscribers programmatically:

# Add a subscriber via the Listmonk REST API
curl -X POST "https://<instance-url>/api/subscribers" \
  -H "Content-Type: application/json" \
  -u "admin:listmonk" \
  -d '{
    "email": "user@example.com",
    "name": "Jane Doe",
    "status": "enabled",
    "lists": [1]
  }'

Using the CLI

# Create a PostgreSQL database first
npx @osaas/cli create birme-osc-postgresql mylistmonkdb \
  -o Password="mypassword"

# Create the Listmonk instance
npx @osaas/cli create knadh-listmonk mynewsletter \
  -o DatabaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres"

Configuration Options

Option Required Description
DatabaseUrl Yes PostgreSQL connection string. Listmonk creates its schema automatically on first start.

Resources