Operator guide

1. Orientation

This is a self-hosted listmonk instance — a newsletter and mailing-list manager. It stores everything in its own PostgreSQL database and sends mail through an external SMTP provider. It is deployed as a Replit Reserved VM from a small bundle of two files.

2. One-time setup checklist

Do these in order, in the admin UI, the first time the instance comes up.

1. Change the bootstrap password and enable TOTP two-factor auth (Admin → your profile).
2. Settings → General: set the root URL to the instance's real HTTPS address. Links, images and unsubscribe URLs in every email are built from this — get it wrong and emails ship broken links.
3. Settings → SMTP: add the provider. For Resend: host smtp.resend.com, port 587, STARTTLS, username resend, password = a dedicated sending API key. Use the Test connection button before saving.
4. Default sender and Reply-To: set both. A missing Reply-To sends replies into the void.
5. Tracking: leave global open and click tracking disabled to start. Turn it on deliberately, later, if you actually need the numbers.
6. Lists: create the lists you need as private, single opt-in unless you specifically want a public signup page or a double opt-in confirmation step. Write down each list's numeric ID — anything integrating over the API needs it.
7. API user: Admin → Users. Create a dedicated user with a role limited to exactly what the integration needs (read/create/update subscribers, manage list membership, post bounces). Do not hand out a super-admin token. The token is shown once — store it immediately.
8. Settings → Media: switch the provider to S3 and point it at a private Cloudflare R2 bucket with a public custom media domain. Enable R2 object versioning.
9. Templates: make sure every campaign template contains an unsubscribe link and a physical/contact footer. See §4.

3. listmonk concepts that matter

Lists

Two axes, and they are independent:

• Public vs private — whether the list appears on the hosted subscription page.
• Single vs double opt-in — double opt-in means a subscriber stays unconfirmed until they click a confirmation link. Campaigns to a double opt-in list only reach confirmed subscribers.

If a campaign reports far fewer recipients than the list size, this is usually why.

Subscribers have two kinds of status

Unsubscribing from one list does not blocklist someone globally. A spam complaint should.

Attributes and segmentation

Every subscriber has a free-form JSON attribs object. This is the interesting part of listmonk: you can query subscribers with raw SQL fragments in the Subscribers page search box, and save the result as a segment for a campaign.

subscribers.attribs->>'city' = 'Dublin'
subscribers.attribs->>'plan' = 'pro' AND subscribers.created_at > now() - interval '30 days'
(subscribers.attribs->'orders')::int >= 2

Test a query on the Subscribers page and check the result count before attaching it to a campaign.

Campaign lifecycle

draft → scheduled → running → paused → finished (or cancelled). A running campaign can be paused and resumed. Sending speed is governed by the message rate and concurrency in Settings → Performance; if you are hitting provider rate limits, that is the dial to turn.

Bounces

Bounce processing has to be switched on in Settings → Bounces, and something has to feed it — either a webhook from your sending provider or a POP3 mailbox. Once enabled you can auto-blocklist or delete a subscriber after N hard bounces. Without this, your list slowly rots and your sending reputation goes with it.

API

Everything in the UI is available over the REST API at /api/*, authenticated with an API user and token:

curl -H "Authorization: token API_USER:API_TOKEN" \
  https://YOUR-DOMAIN/api/lists

BasicAuth (curl -u "API_USER:API_TOKEN") works too. Permissions come from the role you assigned that user.

4. Templates and placeholders

A campaign template is the wrapper (header, footer, styling). The campaign body is dropped into it. Every template must contain exactly one:

{{ template "content" . }}

Available in templates and campaign bodies:

5. Sending a campaign safely

1. Write it, pick the template and the list(s).
2. Check the plain-text version — listmonk can generate it, but auto-generated text from heavy HTML is often unreadable. Mailbox providers penalise HTML-only mail.
3. Send a test to yourself at two or three different providers (Gmail, Outlook, and one other). Check: does it land in Inbox or Spam? Do images load? Does the unsubscribe link work? Does replying reach a real mailbox?
4. Verify SPF, DKIM and DMARC pass on the received message — view the raw headers and look for dkim=pass, spf=pass, dmarc=pass.
5. Only then start the real send. Watch the first minute of the progress counter; if errors are climbing, pause it.

6. How this runs on Replit

The deployment is two files in the repo, and nothing else:

Boot sequence. The launcher first runs a schema upgrade. On an empty database that call fails harmlessly without writing anything, which is the signal to run a first-time install instead. That ordering is deliberate: if the admin bootstrap secrets are missing, the deploy fails while the database is still untouched, rather than leaving a half-configured instance with an unclaimed admin account on a public URL.

Health check. Probe /health — it is public and returns {"data":true}. Do not point a monitor at /api/health; that sits behind API auth and answers 403.

7. Settings it should run with

Secrets

Custom domain

Publish on the .replit.app URL first and confirm the login page loads and data survives a restart. Then add the custom domain under Publishing → Domains and copy the exact A and TXT records into DNS. If Cloudflare manages the DNS, keep the A record DNS-only (grey cloud) so the platform can provision and renew TLS.

8. Upgrading listmonk

1. Back up the database first. Non-negotiable — schema migrations are one-way.
2. Get the new digest from the release's checksums file, linux_amd64 row:
   https://github.com/knadh/listmonk/releases/download/vX.Y.Z/listmonk_X.Y.Z_checksums.txt
3. In build.sh, change both VERSION and EXPECTED_SHA256. Changing one without the other fails the build — that is the safety net working.
4. If the public homepage override is still in use, re-fetch upstream's home.html for the new tag and re-apply the one-line guide link.
5. Rehearse against a restored copy of the backup before touching production.
6. Redeploy. Migrations run automatically on boot.

9. Backups

• Back up PostgreSQL before every upgrade, and on a schedule otherwise.
• Actually restore one. A backup you have never restored is a guess, not a backup.
• Keep R2 object versioning enabled so a bad media overwrite is recoverable.
• Watch deployment logs and restart counts — a VM that keeps restarting is usually a failing boot step, and the logs name it.

10. Troubleshooting

Deploy and boot

Login and access

Email delivery

Domain and TLS

Media

11. Prompts for your AI agent

These are written to be pasted as-is into an agent working in this repo. They are deliberately specific — vague prompts produce vague changes to a system that sends mail to real people.

Deployment and upgrades

Content and templates

Subscribers and data

Deliverability