Send newsletters from listmonk over SMTP

listmonk is a self-hosted newsletter and mailing list manager: it keeps the subscribers and sends campaigns, and delivery is left to the SMTP servers you give it. It keeps a pool of connections to each one and throttles itself, so the settings that matter are the pool, the rate and what happens to bounces and unsubscribes. Below is the setup for Postwing.

SMTP connection settings

Add the SMTP server

Go to Settings → SMTP and edit the existing block or add a new one:

The campaign's From address — and the Default `from` email under Settings → General — must be on your verified domain.

Pool size and timeouts

Save, then use Test connection on the block to send a message to your own address.

Rate limiting

Your plan's hourly limit is enforced by the relay: past it, every message is refused with 550 hourly limit exceeded, and after Maximum error threshold failures listmonk pauses the campaign. Let listmonk pace itself instead — in Settings → Performance:

• Enable sliding window limit on, Duration1h, Max. messages a little under your hourly limit.
• Concurrency × Message rate is the per-second ceiling; the defaults are fine once the window is set.

A new domain's warm-up is different: it never refuses, and over-cap mail is delivered later. See sending limits.

Unsubscribes

With Settings → Privacy → Include `List-Unsubscribe` header on, listmonk adds the one-click unsubscribe pair to every campaign message. When we classify a message as bulk, the relay replaces that pair with its own: the unsubscribe then lands in the domain's unsubscribe list, and later mail to that address is dropped instead of delivered. listmonk still shows the subscriber as active — the unsubscribed webhook tells you who to update. The unsubscribe link in the template itself still goes to listmonk.

Bounces

Turn on Settings → Bounces → Enable bounce processing, set the actions (hard bounce: count 1, action Blocklist), and feed it from one or both sources:

• Bounce mailbox (POP3). Bounce messages go to the envelope sender — the campaign's From, or a Return-Path set in the SMTP block's custom headers. It must be on your verified domain, and the domain's return path in the dashboard must be empty, or it overrides listmonk's.
• Bounce webhooks. A rejection our servers receive during delivery never comes back as a bounce message — it is a bounced webhook. Enable bounce webhooks, create an API user whose role has the webhooks:post_bounce permission, and forward the events:

# Forwards bounced / complained webhook events to listmonk's bounce API.
import hashlib, hmac, os, time
import requests
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]           # the endpoint secret
LISTMONK = "https://lists.your-domain.com"
API_AUTH = ("bounce-bot", os.environ["LISTMONK_TOKEN"])  # listmonk API user
TYPES = {"bounced": "hard", "complained": "complaint"}

@app.post("/hooks/delivery")
def delivery():
    raw = request.get_data(as_text=True)
    ts = request.headers["X-Webhook-Timestamp"]
    sig = request.headers["X-Webhook-Signature"]
    expected = hmac.new(SECRET.encode(), f"{ts}.{raw}".encode(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(ts)) > 300 or not hmac.compare_digest(expected, sig):
        abort(400)

    event = request.get_json()
    if event["event"] in TYPES:
        requests.post(f"{LISTMONK}/webhooks/bounce", auth=API_AUTH, timeout=10, json={
            "email": event["email"],
            "source": "relay",
            "type": TYPES[event["event"]],
        }).raise_for_status()
    return "", 204

Troubleshooting