Listmonk

--- name: software-listmonk description: Manage self-hosted email marketing, newsletters, and transactional emails using Listmonk on the Spark node. metadata: author: skynet version: 1.0.0 --- # Listmonk Operations — James's Fleet Listmonk is the primary self-hosted newsletter and mailing platform for James's fleet. It handles subscriber management, mass campaigns, and transactional emails for various projects (e.g., Affiliate Network, SocialHub). ## Fleet Deployment Status | Machine | IP | Role | Version | Deployment Mode | |---------|-----|------|---------|-----------------| | **Spark** | `192.168.86.48` | **Host** | `v4.1.0` | Docker (App + Postgres 14) | | Workstation | `192.168.86.22` | Client | N/A | API Access / CLI Control | | Dev Server | `192.168.86.33` | Client | N/A | Transactional Relay | ### Infrastructure Details (Spark) - **App Container:** `listmonk_app` (Port 9000 by default) - **Database Container:** `listmonk_db` (Postgres 14) - **Database Port:** `5433` (Spark's Postgres hub) - **Config Path:** `/home/skynet/infra/listmonk/` - **Storage:** Persisted via Docker volumes on Spark's NVMe. ## Key Commands & Operations ### Docker Management Use these commands on **Spark** to manage the service: ```bash # View status and health docker ps | grep listmonk # View application logs docker logs -f listmonk_app # Restart the service after config changes docker restart listmonk_app ``` ### Administrative CLI Run commands inside the container for maintenance: ```bash # Check version and help docker exec -it listmonk_app ./listmonk --version # Perform a database upgrade (if version changed) docker exec -it listmonk_app ./listmonk --upgrade --config config.toml # Reset admin password (interactive) docker exec -it listmonk_app ./listmonk --password-reset ``` ### API Access (Internal Fleet) Agents can interact with Listmonk via the REST API from any machine in the fleet: - **Base URL:** `http://192.168.86.48:9000/api` - **Authentication:** Basic Auth (retrieve credentials from Vault Mac if needed). ```bash # List all campaigns curl -u user:pass http://192.168.86.48:9000/api/campaigns # Add a subscriber curl -X POST -u user:pass http://192.168.86.48:9000/api/subscribers \ -H "Content-Type: application/json" \ -d '{"email": "test@example.com", "name": "Test User", "status": "enabled", "lists": [1]}' ``` ## Configuration Locations - **Main Config:** `/home/skynet/infra/listmonk/config.toml` - Defines DB connection, app address, and security keys. - **Deployment:** `/home/skynet/infra/listmonk/docker-compose.yml` - Manages image versions and volume mounts. - **Static Assets:** Custom templates and media should be stored in the Spark infra directory and mounted into the container. ## Common Workflows ### 1. Subscriber Import - **Bulk Import (CSV):** Best performed via the Web UI at `:9000/admin/subscribers/import`. - **API Import:** Use for real-time signups from landing pages (e.g., projects on Dev Server). - **CLI Import:** `docker exec -i listmonk_app ./listmonk --import subscribers.csv` ### 2. Campaign Management - **Templates:** Use Go-templating (`{{ .Subscriber.FirstName }}`). - **Media:** Assets are served via Spark's public-facing IP or proxied through Caddy on Dev Server. - **Sending:** Ensure Spark's SMTP settings are configured for the fleet's mail provider (e.g., Amazon SES or SendGrid). ### 3. Transactional Emails Listmonk provides a `/api/tx` endpoint for sending system-generated emails (password resets, alerts). - **Reference:** [Listmonk Transactional API Docs](https://listmonk.app/docs/apis/transactional/) ## Troubleshooting ### Connection Issues - **DB Connection Failed:** Ensure `listmonk_db` is running on Spark and listening on port `5433`. - **SMTP Timeout:** Spark's ethernet is down; ensure Tailscale/WiFi connectivity allows outbound traffic on port 587/465. - **Internal 500 Errors:** Check `docker logs listmonk_app` for template syntax errors or missing DB migrations. ### Performance - Spark has 128GB of RAM; for large campaigns (100k+), increase `app.concurrency` and `app.message_rate` in `config.toml`. - DB backups: Regularly export Postgres data on Spark using `pg_dump`. ## Fleet-Specific Patterns - **Spark as Hub:** All mailing infrastructure is consolidated on Spark to leverage its high uptime and resources. - **Relay Pattern:** Applications on Dev Server (192.168.86.33) should NOT send mail directly; they must POST to the Listmonk API on Spark. - **Monitoring:** Check the Listmonk dashboard at `http://192.168.86.48:9000` for real-time bounce and click metrics.