listmonk

Listmonk is a self‑hosted, high‑performance newsletter and mailing list engine that bundles its entire runtime into a single Go binary. The core idea is to give developers a lightweight, maintainable platform that can be deployed on anything from a single VPS to a Kubernetes cluster. The application exposes both a web UI and a RESTful API, allowing integration into existing CI/CD pipelines or custom front‑ends. Under the hood it leverages PostgreSQL for persistence, Go’s concurrency primitives for high throughput, and a Vue‑based SPA for an interactive admin experience.

Technical Stack & Architecture

• Backend: Go (1.22+), using the standard library’s net/http along with a router such as chi. The codebase is organized into domain‑driven packages (campaign, subscriber, analytics) and a thin service layer that orchestrates database access, templating, and email delivery.
• Frontend: Vue 3 with Buefy (Bulma) for UI components, compiled to a single SPA served by the Go server. The frontend communicates with the backend exclusively via JSON over HTTPS, making it a perfect candidate for headless or micro‑frontend deployments.
• Database: PostgreSQL is the sole data store, accessed via sqlx for named parameters and scan helpers. The schema is deliberately flat to keep migrations fast; all subscriber attributes are stored in a JSONB column, enabling dynamic segmentation without schema churn.
• Email Delivery: Listmonk ships with an SMTP client that supports TLS, DKIM signing (via Go’s crypto package), and a pluggable transport layer. For higher throughput, it can be paired with an external MTA like Postfix or a cloud service via webhook callbacks.
• Deployment: The single binary can be run directly or as a Docker container (listmonk/listmonk:latest). Kubernetes manifests are provided in the repo, and the app is stateless apart from its database, making horizontal scaling trivial.

Core Capabilities & Developer APIs

• Campaign Management: Create, schedule, and send campaigns. The API exposes endpoints for CRUD operations (/api/v1/campaigns) and batch sending, returning detailed delivery reports.
• Subscriber Lifecycle: Subscribe/unsubscribe flows are fully API‑driven, with support for double opt‑in via confirmation tokens. The subscriber model exposes a segment field that can be queried with raw SQL expressions, enabling complex segmentation without custom code.
• Templating Engine: Listmonk uses Go’s text/template and html/template packages, allowing developers to embed logic (if, range) and a rich set of built‑in functions (date formatting, string manipulation). Templates are stored in the database and can be edited via the UI or API.
• Analytics & Reporting: The API returns JSON metrics (opens, clicks, bounces) aggregated per campaign. A lightweight GraphQL endpoint is also available for ad‑hoc queries, useful in dashboards or third‑party analytics tools.
• Webhooks: Outbound events (delivery, bounce, click) can be pushed to any HTTP endpoint, enabling real‑time processing or integration with CRMs. Incoming webhooks can trigger custom actions like auto‑tagging subscribers.

Deployment & Infrastructure

• Self‑Hosting: Listmonk requires only a PostgreSQL instance and an SMTP server. The binary is platform‑agnostic (Linux, macOS, Windows) and can run on ARM or x86.
• Scalability: Because the service is stateless, you can run multiple replicas behind a load balancer. PostgreSQL must be scaled appropriately; read replicas are supported for analytics queries, and connection pooling (pgbouncer) is recommended.
• Containerization: The official Docker image exposes environment variables for configuration (DATABASE_URL, SMTP_*). A sample docker‑compose.yml ships with the repo, making a local dev environment trivial.
• CI/CD: The API’s RESTful nature and idempotent migration scripts make it easy to integrate Listmonk into GitHub Actions or Jenkins pipelines for automated deployment.

Integration & Extensibility

• Plugins: While Listmonk does not have a formal plugin system, its modular Go architecture allows developers to fork the repo and add custom services (e.g., a new email provider). The public API can be extended by adding new endpoints.
• Webhooks & Callbacks: Almost every critical event emits a webhook, enabling integration with external services such as Salesforce, HubSpot, or custom analytics dashboards.
• Custom UI: The SPA is built with Vue, so developers can fork the frontend and replace it with a custom UI or integrate Listmonk’s API into an existing application.

Developer Experience

• Documentation: The official docs cover installation, API reference, and developer setup. They include example payloads and error codes, making onboarding fast for Go or JavaScript developers.
• Community & Support: The project is maintained on GitHub with an active issue tracker. Contributions are welcome under AGPLv3, and the core team responds promptly to pull requests.
• Configuration: A config.toml file exposes all tunable parameters (SMTP, database, feature flags). The binary can generate a fresh config with --new-config, simplifying initial setup.

Use Cases

1. Startup Email Marketing – Deploy Listmonk on a single droplet to send