Listmonk Exporter

A Prometheus exporter for Listmonk, the self-hosted newsletter and mailing list manager. Monitor your email campaigns, subscriber counts, bounce rates, and more with this lightweight exporter.

Features

• 📊 Subscriber Metrics: Track subscriber counts by status (confirmed, unconfirmed, unsubscribed)
• 📧 Campaign Statistics: Monitor sent, opened, clicked, and bounced emails per campaign
• 📋 List Metrics: View subscriber counts across all your lists
• 🔄 Bounce Tracking: Track bounce counts by type (hard, soft, complaint)
• ⚡ Lightweight: Built with Python and runs as a single process
• 🐳 Docker Ready: Includes official Docker image for easy deployment
• 🔧 Configurable: Flexible configuration via environment variables or CLI arguments

Installation

Via pip

pip install listmonk-exporter

Via Docker

docker pull ghcr.io/meysam81/listmonk-exporter:latest

Configuration

Configure the exporter using environment variables or command-line arguments.

Required Configuration

Optional Configuration

Usage

Quick Start with pip

# Set required environment variables
export LISTMONK_HOST=https://listmonk.example.com
export LISTMONK_API_USER=admin
export LISTMONK_API_TOKEN=your-api-token
export LIST_ID=1
export LIST_NAME="Newsletter"

# Run the exporter
listmonk-exporter

Docker Compose

version: "3.8"

services:
  listmonk-exporter:
    image: ghcr.io/meysam81/listmonk-exporter:latest
    ports:
      - "8000:8000"
    environment:
      LISTMONK_HOST: https://listmonk.example.com
      LISTMONK_API_USER: admin
      LISTMONK_API_TOKEN: your-api-token
      LIST_ID: 1
      LIST_NAME: Newsletter
      SCRAPE_INTERVAL: 60
      LOG_LEVEL: INFO
    restart: unless-stopped

Docker Run

docker run -d \
  -p 8000:8000 \
  -e LISTMONK_HOST=https://listmonk.example.com \
  -e LISTMONK_API_USER=admin \
  -e LISTMONK_API_TOKEN=your-api-token \
  -e LIST_ID=1 \
  -e LIST_NAME=Newsletter \
  ghcr.io/meysam81/listmonk-exporter:latest

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: listmonk-exporter
spec:
  replicas: 1
  selector:
    matchLabels:
      app: listmonk-exporter
  template:
    metadata:
      labels:
        app: listmonk-exporter
    spec:
      containers:
        - name: listmonk-exporter
          image: ghcr.io/meysam81/listmonk-exporter:latest
          ports:
            - containerPort: 8000
          env:
            - name: LISTMONK_HOST
              value: "https://listmonk.example.com"
            - name: LISTMONK_API_USER
              valueFrom:
                secretKeyRef:
                  name: listmonk-credentials
                  key: username
            - name: LISTMONK_API_TOKEN
              valueFrom:
                secretKeyRef:
                  name: listmonk-credentials
                  key: token
            - name: LIST_ID
              value: "1"
            - name: LIST_NAME
              value: "Newsletter"
---
apiVersion: v1
kind: Service
metadata:
  name: listmonk-exporter
spec:
  selector:
    app: listmonk-exporter
  ports:
    - port: 8000
      targetPort: 8000

Exported Metrics

The exporter provides the following Prometheus metrics:

Metric Details

Subscriber Metrics:

• subscription_status values: confirmed, unconfirmed, unsubscribed

Campaign Metrics:

• stat_type values: sent, opened, clicked, bounced
• campaign_status values: draft, scheduled, running, paused, finished, cancelled

Bounce Metrics:

• bounce_type values: hard, soft, complaint

Exporter Metrics:

• operation values: subscribers, campaigns, lists, bounces

Prometheus Configuration

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: "listmonk"
    static_configs:
      - targets: ["localhost:8000"]

Note: For complete configuration examples including scrape jobs and alerting rules, see the examples directory.

Grafana Dashboard

Import the provided Grafana dashboard (coming soon) or create your own using the exported metrics.

Example queries:

# Total subscribers
listmonk_subscribers_total{list_name="Newsletter"}

# Confirmed subscribers
listmonk_subscribers_by_status{list_name="Newsletter",subscription_status="confirmed"}

# Campaign open rate
(listmonk_campaign_stats{stat_type="opened"} / listmonk_campaign_stats{stat_type="sent"}) * 100

Development

Prerequisites

• Python 3.11 or higher
• pip

Setup

# Clone the repository
git clone https://github.com/meysam81/listmonk-exporter.git
cd listmonk-exporter

# Install dependencies
pip install -e .

# Run locally
python main.py

Building Docker Image

docker build -t listmonk-exporter .

Troubleshooting

Exporter can't connect to Listmonk

• Verify LISTMONK_HOST is correct and accessible
• Check that API credentials are valid
• Ensure Listmonk API is enabled

Metrics not updating

• Check SCRAPE_INTERVAL setting
• Review logs with LOG_LEVEL=DEBUG
• Verify the list ID exists in Listmonk

High memory usage

• Increase SCRAPE_INTERVAL to reduce scraping frequency
• Check Listmonk API response sizes

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Support

• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: [Your email]

Acknowledgments

• Listmonk - The amazing newsletter manager
• Prometheus - Monitoring and alerting toolkit
• prometheus_client - Python client for Prometheus

Made with ❤️ for the open-source community.