# Listmonk — Self-Hosted Newsletter & Mailing List Manager

> Listmonk is a high-performance, self-hosted newsletter and mailing list manager with a modern dashboard. Single binary, handles millions of subscribers efficiently.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name listmonk 
  -p 9000:9000 
  -e "LISTMONK_DB_HOST=host.docker.internal" 
  -e "LISTMONK_DB_PORT=5432" 
  -e "LISTMONK_DB_USER=listmonk" 
  -e "LISTMONK_DB_PASSWORD=listmonk" 
  -e "LISTMONK_DB_DATABASE=listmonk" 
  listmonk/listmonk:latest
```

Or use the all-in-one Docker Compose:
```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/knadh/listmonk/master/docker-compose.yml
docker compose up -d
# Run setup
docker compose run --rm app ./listmonk --install
```

Open `http://localhost:9000` — login with admin/admin.

## Intro

**Listmonk** is a high-performance, self-hosted newsletter and mailing list manager. Built with Go and React, it provides a modern web dashboard for managing subscribers, creating email campaigns, and tracking analytics — all from a single binary that can handle millions of subscribers with minimal resources.

With 19.5K+ GitHub stars and AGPL-3.0 license, Listmonk is the go-to self-hosted alternative to Mailchimp, ConvertKit, and SendGrid for organizations that want full control over their email marketing with zero per-subscriber costs.

## What Listmonk Does

- **Subscriber Management**: Import, segment, and manage subscriber lists with custom attributes
- **Campaign Creation**: Rich HTML email editor with template support and media management
- **Transactional Email**: API for sending transactional emails (welcome, reset, notifications)
- **Analytics**: Open rates, click rates, bounce tracking, and campaign performance metrics
- **List Segmentation**: Dynamic segments based on subscriber attributes and engagement
- **Double Opt-in**: Configurable double opt-in with customizable confirmation emails
- **Template System**: Go template engine for dynamic, personalized email content
- **Multi-list**: Manage multiple independent mailing lists from one instance
- **SMTP Integration**: Works with any SMTP provider (SES, Postmark, SendGrid, self-hosted)
- **API**: Full REST API for programmatic subscriber and campaign management

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Admin UI    │────▶│  Listmonk    │────▶│  PostgreSQL  │
│  (React)     │     │  Server (Go) │     │  (Subscribers│
└──────────────┘     └──────┬───────┘     │  & Campaigns)│
                            │             └──────────────┘
                     ┌──────┴───────┐
                     │  SMTP Server │
                     │  (SES/SMTP)  │
                     └──────────────┘
```

## Self-Hosting

### Docker Compose (Recommended)

```yaml
services:
  listmonk:
    image: listmonk/listmonk:latest
    ports:
      - "9000:9000"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./config.toml:/listmonk/config.toml
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: listmonk
      POSTGRES_PASSWORD: listmonk
      POSTGRES_DB: listmonk
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data:
```

### SMTP Configuration

```toml
# config.toml
[smtp]
  host = "email-smtp.us-east-1.amazonaws.com"
  port = 587
  auth_protocol = "login"
  username = "YOUR_SES_KEY"
  password = "YOUR_SES_SECRET"
  tls_type = "STARTTLS"
  max_conns = 10
  idle_timeout = "15s"
  wait_timeout = "5s"
```

Recommended SMTP providers:
- **Amazon SES**: $0.10/1000 emails (cheapest at scale)
- **Postmark**: $1.25/1000 emails (best deliverability)
- **SendGrid**: 100/day free, then $0.50/1000
- **Self-hosted**: Postfix/Haraka (free but requires IP reputation management)

## Key Features

### Campaign Templates

```html
<!-- Use Go template syntax -->
<h1>Hello {{ .Subscriber.FirstName }}!</h1>

{{ if eq .Subscriber.Attribs.plan "pro" }}
  <p>As a Pro subscriber, you get early access to...</p>
{{ else }}
  <p>Upgrade to Pro for exclusive content...</p>
{{ end }}

<a href="{{ .TrackLink "https://example.com/offer" }}">
  Check out our latest offer
</a>

<p>Unsubscribe: {{ .UnsubscribeURL }}</p>
```

### REST API

```bash
# Add subscriber
curl -X POST http://localhost:9000/api/subscribers 
  -u "admin:admin" 
  -H "Content-Type: application/json" 
  -d '{"email": "user@example.com", "name": "John", "lists": [1], "attribs": {"plan": "free"}}'

# Send transactional email
curl -X POST http://localhost:9000/api/tx 
  -u "admin:admin" 
  -H "Content-Type: application/json" 
  -d '{"subscriber_email": "user@example.com", "template_id": 1, "data": {"order_id": "12345"}}'

# Create campaign
curl -X POST http://localhost:9000/api/campaigns 
  -u "admin:admin" 
  -H "Content-Type: application/json" 
  -d '{"name": "Weekly Update", "subject": "This Week in Tech", "lists": [1], "type": "regular", "content_type": "richtext", "body": "<h1>Hello!</h1>"}'
```

### Subscriber Import

Import from CSV with custom attribute mapping:
```csv
email,name,plan,signup_date
john@example.com,John Doe,pro,2024-01-15
jane@example.com,Jane Smith,free,2024-02-20
```

Supports importing hundreds of thousands of subscribers in seconds.

## Listmonk vs Alternatives

| Feature | Listmonk | Mailchimp | ConvertKit | Buttondown |
|---------|----------|-----------|------------|------------|
| Open Source | Yes (AGPL-3.0) | No | No | No |
| Self-hosted | Yes | No | No | No |
| Cost per 10K subs | $0 (+ SMTP) | $78/mo | $119/mo | $39/mo |
| Transactional | Yes | Separate (Mandrill) | No | No |
| Performance | Millions of subs | Unlimited | 500K limit | 100K limit |
| Template engine | Go templates | Drag & drop | Visual | Markdown |
| API | Full REST | Full REST | Full REST | Full REST |

## FAQ

**Q: What's Listmonk's email deliverability like?**
A: Deliverability depends on your SMTP provider and domain configuration (SPF, DKIM, DMARC), not on Listmonk itself. Using professional services like Amazon SES or Postmark can achieve 95%+ deliverability.

**Q: How many subscribers can it handle?**
A: A single Listmonk instance easily manages millions of subscribers. The Go backend is extremely efficient; send speed is mainly limited by SMTP, not Listmonk itself.

**Q: Does it support automated email sequences?**
A: Listmonk currently focuses on one-time and scheduled campaigns. Automated sequences (like welcome drips) can be built with the API + an external scheduler. Native automation is on the roadmap.

## Source & Thanks

- GitHub: [knadh/listmonk](https://github.com/knadh/listmonk) — 19.5K+ ⭐ | AGPL-3.0
- Website: [listmonk.app](https://listmonk.app)

---
Source: https://tokrepo.com/en/workflows/listmonk-self-hosted-newsletter-mailing-list-manager-ed7b1e03
Author: AI Open Source