Listmonk Has a Free API: Self-Hosted Newsletter and Email Marketing Platform

#email #opensource #selfhosted #tutorial

What is Listmonk?

Listmonk is a self-hosted newsletter and mailing list manager — an alternative to Mailchimp, ConvertKit, and Buttondown. Send transactional and marketing emails to millions of subscribers from your own server.

Free. Unlimited subscribers. Unlimited emails.

Quick Start

mkdir listmonk && cd listmonk
curl -sL https://github.com/knadh/listmonk/releases/latest/download/docker-compose.yml -o docker-compose.yml
docker compose up -d
./listmonk --install

Open http://localhost:9000 — admin: listmonk / listmonk.

The REST API

export LM_URL="http://localhost:9000/api"
# Uses Basic Auth
export LM_AUTH="listmonk:your-password"

Subscribers

# Add subscriber
curl -X POST "$LM_URL/subscribers" \
  -u "$LM_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "Alice Johnson",
    "status": "enabled",
    "lists": [1],
    "attribs": {"plan": "pro", "source": "website"}
  }'

# List subscribers
curl -s "$LM_URL/subscribers?page=1&per_page=50" \
  -u "$LM_AUTH" | jq '.data.results[] | {email, name, status}'

# Search
curl -s "$LM_URL/subscribers?query=subscribers.email LIKE '%example.com'" \
  -u "$LM_AUTH"

# Update subscriber
curl -X PUT "$LM_URL/subscribers/SUBSCRIBER_ID" \
  -u "$LM_AUTH" \
  -d '{"name": "Alice Smith", "attribs": {"plan": "enterprise"}}'

Lists

# Create list
curl -X POST "$LM_URL/lists" \
  -u "$LM_AUTH" \
  -d '{"name": "Weekly Newsletter", "type": "public", "optin": "double"}'

# Get lists
curl -s "$LM_URL/lists" -u "$LM_AUTH" | jq '.data.results[] | {name, subscriber_count}'

Campaigns

# Create campaign
curl -X POST "$LM_URL/campaigns" \
  -u "$LM_AUTH" \
  -d '{
    "name": "March Newsletter",
    "subject": "What we shipped this month",
    "lists": [1],
    "type": "regular",
    "content_type": "richtext",
    "body": "<h1>March Update</h1><p>Here is what we shipped...</p>",
    "from_email": "newsletter@myapp.com"
  }'

# Start campaign
curl -X PUT "$LM_URL/campaigns/CAMPAIGN_ID/status" \
  -u "$LM_AUTH" \
  -d '{"status": "running"}'

# Get campaign stats
curl -s "$LM_URL/campaigns/CAMPAIGN_ID" \
  -u "$LM_AUTH" | jq '{status, sent: .sent, views: .views, clicks: .clicks}'

Transactional Email

curl -X POST "$LM_URL/tx" \
  -u "$LM_AUTH" \
  -d '{
    "subscriber_email": "user@example.com",
    "template_id": 1,
    "data": {
      "order_id": "ORD-123",
      "total": "$49.99",
      "items": ["Widget Pro", "Gadget Plus"]
    }
  }'

Templates

curl -X POST "$LM_URL/templates" \
  -u "$LM_AUTH" \
  -d '{
    "name": "Order Confirmation",
    "type": "tx",
    "body": "<h1>Order {{.Tx.Data.order_id}}</h1><p>Total: {{.Tx.Data.total}}</p>"
  }'

Features

Newsletters: Rich text and HTML campaigns
Transactional: Order confirmations, password resets
Segmentation: Query-based subscriber segments
Templates: Go templating with custom data
Analytics: Opens, clicks, bounces
Double opt-in: GDPR compliance
SMTP/SES/Postmark: Any email provider

Listmonk vs Mailchimp

Feature	Listmonk	Mailchimp Free	ConvertKit
Subscribers	Unlimited	500	1,000
Emails/mo	Unlimited	1,000	Unlimited
Cost	$0 (self-host)	$0 (limited)	$29/mo
API	Full REST	REST	REST
Templates	Unlimited	Limited	Limited
Custom domain	Yes	Paid	Paid