Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

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.

TL;DR — Immediate Production Fix

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.

docker-compose.yml
yaml
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`.

amazon-ses-mumbai-smtp-settings.json
json
{
  "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-ses-bounce-webhook.sh
bash
# 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.
India's First & Only Developer PaaS

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`).

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →