Production Listmonk Newsletter Server Docker Compose Template with PostgreSQL 16 & AWS SES
Deploy Listmonk v4+ self-hosted newsletter and transactional email manager with Docker Compose, PostgreSQL 16, and Amazon SES (ap-south-1 Mumbai). Includes automatic DB migrations and bounce webhooks.
Listmonk (`listmonk/listmonk:latest`) is a high-performance Go binary backed by PostgreSQL that sends 100,000+ emails for ~$10 via Amazon SES while using less than 40 MB of RAM. When deploying Listmonk in Docker Compose without a mounted `config.toml` file, you must pass double-underscore environment variables (`LISTMONK_db__host=postgres`, `LISTMONK_db__ssl_mode=disable`) AND chain `./listmonk --install --idempotent --yes --config="" && ./listmonk --upgrade --yes --config="" && ./listmonk --config=""` in the container `command:` so fresh installations and version upgrades never fail with missing database tables.
Verified Root Causes in Production Environments
- Missing --install --idempotent --yes on First Boot: Starting `./listmonk` against an empty PostgreSQL database without running `--install --idempotent --yes` causes the container to crash with `relation "settings" does not exist`.
- Passing --config=config.toml When Using Environment Variables: If you only configure Listmonk via `LISTMONK_*` environment variables, you must pass `--config=""` (empty string) so Listmonk does not abort looking for a missing `config.toml` file.
- Using AWS IAM Keys Instead of SES SMTP Credentials: Amazon SES requires dedicated SMTP credentials generated in the SES Console (`email-smtp.ap-south-1.amazonaws.com:587` with `STARTTLS`), not standard AWS IAM `AKIA*` access keys.
1. Zero-Config-File Production docker-compose.yml With Auto-Migrations
Many older Listmonk tutorials tell you to run an interactive `docker compose run --rm app ./listmonk --install` step manually and manage a mounted `config.toml` file. In automated PaaS environments like Coolify and Vexlo Cloud, a much cleaner pattern is passing `--config=""` and chaining `--install --idempotent --yes` with `--upgrade --yes` directly in the container's startup command.
Because `--idempotent` is a no-op if the database schema already exists, and `--upgrade` safely applies any new migrations when you pull a newer Listmonk version, your deployment becomes 100% hands-free.
services:
listmonk-db:
image: postgres:16-alpine
container_name: vexlo-listmonk-db
restart: unless-stopped
environment:
POSTGRES_USER: listmonk
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: listmonk
volumes:
- listmonk_pg_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U listmonk -d listmonk"]
interval: 10s
timeout: 5s
retries: 5
listmonk-app:
image: listmonk/listmonk:latest
container_name: vexlo-listmonk
restart: unless-stopped
# Automatically initialize DB on first boot, run schema upgrades, and start server
command: >
sh -c "./listmonk --install --idempotent --yes --config='' &&
./listmonk --upgrade --yes --config='' &&
./listmonk --config=''"
ports:
- "127.0.0.1:9000:9000"
environment:
LISTMONK_app__address: "0.0.0.0:9000"
LISTMONK_db__host: listmonk-db
LISTMONK_db__port: 5432
LISTMONK_db__user: listmonk
LISTMONK_db__password: ${POSTGRES_PASSWORD}
LISTMONK_db__database: listmonk
LISTMONK_db__ssl_mode: disable
LISTMONK_ADMIN_USER: ${LISTMONK_ADMIN_USER:-admin}
LISTMONK_ADMIN_PASSWORD: ${LISTMONK_ADMIN_PASSWORD}
TZ: Asia/Kolkata
volumes:
- listmonk_uploads:/listmonk/uploads
depends_on:
listmonk-db:
condition: service_healthy
volumes:
listmonk_pg_data:
listmonk_uploads:2. Configuring Amazon SES Mumbai (ap-south-1) SMTP & Throughput Rates
Once you log into the Listmonk Admin UI (`Settings -> SMTP`), configure Amazon SES in the `ap-south-1` (Mumbai) region using host `email-smtp.ap-south-1.amazonaws.com`, port `587`, TLS type `STARTTLS`, and Auth Protocol `LOGIN`.
Critical: Match Listmonk's `Max connections` and `Message sliding window rate` (`Settings -> Performance`) to stays ~10% below your AWS SES account's per-second sending quota (e.g., if your SES quota is 14 emails/sec, set Listmonk sliding window to `12/second`) so SES never throttles your campaign with `454 Throttling failure: Maximum sending rate exceeded`.
{
"smtpHost": "email-smtp.ap-south-1.amazonaws.com",
"smtpPort": 587,
"authProtocol": "login",
"tlsType": "STARTTLS",
"username": "AKIA... (Generate in AWS SES Console -> SMTP Settings, NOT regular IAM user!)",
"maxConnections": 10,
"idleTimeoutSeconds": 15,
"bounceWebhookEndpoint": "https://newsletter.vexlo.cloud/webhooks/service/ses"
}3. Enabling AWS SNS -> Listmonk Bounce & Complaint Webhooks
Amazon SES suspends accounts whose hard bounce rate exceeds 5% or complaint rate exceeds 0.1%. To automatically blocklist hard-bouncing addresses in Listmonk, enable `Settings -> Bounces -> Enable bounce webhooks -> Enable SES`, create an AWS SNS topic subscribed to `https://newsletter.vexlo.cloud/webhooks/service/ses` (HTTPS protocol), and attach that SNS topic to your verified SES domain's Bounce and Complaint notifications.
When sending high-volume campaigns from a new domain on Amazon SES Mumbai (ap-south-1), verify both SPF (v=spf1 include:amazonses.com ~all) and Easy DKIM (three CNAME records) alongside a strict DMARC policy (_dmarc TXT record: v=DMARC1; p=quarantine; pct=100;) in Cloudflare DNS. Gmail and Yahoo Mail reject bulk senders (>5,000 emails/day) that lack aligned DKIM, SPF, and List-Unsubscribe headers—which Listmonk injects automatically on every campaign.
# Verify Listmonk's public SES SNS bounce webhook endpoint is reachable (returns 400 on empty GET/POST)
curl -i -X POST https://newsletter.vexlo.cloud/webhooks/service/ses \
-H "Content-Type: application/json" \
-d '{"Type":"Notification"}'Pre-Deployment Verification Checklist
- Pass `--config=''` when configuring Listmonk exclusively via `LISTMONK_*` environment variables.
- Include `./listmonk --install --idempotent --yes --config='' && ./listmonk --upgrade --yes --config=''` in the container startup command.
- Generate dedicated SES SMTP credentials in the AWS SES Console rather than using raw IAM access keys.
- Configure AWS SNS bounce/complaint webhooks to `/webhooks/service/ses` before sending production campaigns.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does Listmonk fail to connect to PostgreSQL with 'pq: SSL is not enabled on the server'?
PostgreSQL Docker images disable SSL on internal container networks by default. Add `LISTMONK_db__ssl_mode: disable` (note the double underscore between `db` and `ssl_mode`) to your Listmonk container environment variables.
Why does Amazon SES return '535 Authentication Credentials Invalid' in Listmonk?
You are using standard AWS IAM Access Key ID / Secret Access Key instead of SES SMTP credentials. Open the AWS SES Console -> SMTP Settings -> Create SMTP Credentials to generate the derived SMTP password.
How do I send transactional emails (like OTPs or invoices) through Listmonk's API?
Create a template of type `Transactional` in the Listmonk UI, create an API User with the `tx:send` permission under `Settings -> Users`, and `POST /api/tx` with Basic Auth (`username:api_token`).