Listmonk — SKILL.md

---
name: "Listmonk"
description: "Fleet skill: Listmonk — software inventory and operations reference"
version: "1.0.0"
author: "skynet"
category: "fleet"
agents: ["claude-code", "codex", "gemini", "kimi"]
tags: ["software-listmonk", "fleet", "fleet", "software"]
---

# 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.