SKILL.md

Listmonk Publisher

Listmonk is a single Go binary plus PostgreSQL that scales to millions of subscribers at near-zero per-email cost through an SMTP relay. It buys data sovereignty and price control, and it costs you deliverability ownership. Default to hosted until a trigger fires.

Deploy or defer

Deploy Listmonk when at least one holds:

Hosted pricing breaks at your list size (typically 100k+ subscribers where hosted tiers jump 3-4x).
You need full data sovereignty (EU or regulated verticals).
You want near-zero marginal send cost via SES or similar (~$0.10 per 1k emails).

None hold: stay on the hosted platform as primary. Keep Listmonk as the documented exit path, that alone is negotiating leverage against lock-in.

Setup

Run PostgreSQL, then the Listmonk binary or container on an internal port (default 9000). Do not expose the admin UI publicly, put it behind a reverse proxy with auth or a private network.
Configure an SMTP relay (Amazon SES, Postmark, or similar). Sending from a raw VPS IP is a deliverability death sentence.
Set DNS before the first send: SPF, DKIM, and DMARC records for the sending domain, verified in the relay's console.
Store credentials as env vars: $LISTMONK_URL, $LISTMONK_API_USER, $LISTMONK_API_KEY. Never in the repo.
Create lists and enable double opt-in. Import existing subscribers only with their opt-in provenance intact.

Operate

Publish campaigns via the admin UI or POST /api/campaigns with the API key, always to a test list first.
Segment with SQL-based subscriber queries, that is Listmonk's edge over hosted tools.
Warm up a new sending domain: start with your most engaged segment, grow volume over weeks.
Watch bounce and complaint rates in the relay console after every send, not monthly.

Alternatives map

Listmonk (Go, AGPL): fastest, leanest. Mautic (PHP, GPL): full marketing automation, heaviest. Keila (Elixir, AGPL): Mailchimp-like UI. Ghost (Node, MIT): CMS with newsletter, see ghost-publisher. Postal (Ruby, MIT): SMTP server for transactional, not a list manager.

Good vs bad

Bad: 4k subscribers, hosted plan is cheap, but "self-hosted is cooler", so a weekend goes into Listmonk plus SES, DKIM never gets set, and the first campaign lands in spam for half the list.

Good: 120k subscribers, hosted bill about to triple. Deploy Listmonk with SES, verify SPF/DKIM/DMARC, warm the domain on the most engaged 10%, migrate segment by segment while watching bounce rates, and cut the bill by an order of magnitude.

Verification

Before the first real campaign, send a test campaign to a seed list including Gmail and Outlook addresses. Check headers on the received mail. Expect: spf=pass, dkim=pass, dmarc=pass, landing in the inbox, not spam. Any fail: fix DNS and relay config before sending to subscribers, warming a burned domain takes months.

Completion checklist

[ ] Deploy decision backed by a trigger, not preference
[ ] Admin UI not publicly exposed
[ ] SMTP relay configured, no direct-IP sending
[ ] SPF, DKIM, DMARC verified passing on a seed test
[ ] Credentials in env vars only
[ ] Double opt-in on, import provenance clean
[ ] Domain warm-up plan for new sending domains

Any box unchecked: not done. Fix or say so.

Footguns

DNS skipped, domain burned. Sends without SPF/DKIM/DMARC train providers to junk your domain, and the reputation damage outlives the fix. Fix: verify all three pass on a seed test before any subscriber send.
Full-volume day one. A fresh domain blasting 100k emails looks exactly like a spammer. Fix: warm up over weeks, engaged segments first.
Dirty list import. Importing scraped or stale addresses spikes bounces and gets the relay account suspended. Fix: import only provable opt-ins, run a hygiene pass on anything old.

listmonk-publisher

SKILL.md