Start
/Resources
/Backend
/How to Contribute
/KumoMTA SMTP Engine Setup

KumoMTA SMTP Engine Setup

Learn how to configure and run the Reloop KumoMTA SMTP mail engine locally and in Docker.

The KumoMTA SMTP Engine is a high-performance, developer-first ESMTP Mail Transfer Agent (MTA) designed to handle large-scale, high-velocity outbound mail queues. It runs inside a Docker container, configured with custom Lua policy scripts that govern outbound throttling, connection pooling, and delivery webhooks callback generation.

Prerequisite First

Before starting the KumoMTA SMTP Engine, make sure you've completed the base Local Development Setup and have Docker Desktop running.

Service Information

  • Directory Location: apps/backend/kumomta-smtp/
  • Docker Service Name: kumomta-smtp (configured in local/docker-compose.yml)
  • Local SMTP Port Bind: 25 (ESMTP inbound ingestion)
  • Local HTTP Port Bind: 8020 (proxies KumoMTA internal console port 8000)
  • Tech Stack: KumoMTA (C++ SMTP Engine Core), Lua policy configs
  • Dependencies: Relies on reloop-mailpit (port 1025/8025) in local development as a safe sandbox sink for outgoing mail.

How It Works

  1. SMTP Ingestion: The ESMTP listener on port 25 accepts incoming email delivery streams generated by the platform's mailing service.
  2. Spool Directory Volume: Incoming messages are persisted securely to Docker volumes (/var/spool/kumomta/data and /var/spool/kumomta/meta) to ensure zero-loss crash recovery.
  3. Lua Policy Execution: The init.lua entrypoint and sub-policies under /policy/ are executed dynamically by KumoMTA to configure connection limits, routing rules, DKIM signatures, and webhook events.
  4. Outbound Dispatch: The engine attempts to deliver the message to destination MX servers, or routes it locally to Mailpit (1025) during development.

Configuration Variables

The container variables are mapped in the local/docker-compose.yml service specification:

VariableDefault ValueDescription
X_KUMOMTA_KEYreloopThe shared security key token sent by KumoMTA to authorize webhook logs.
BASE_URLhttps://local.reloop.shReloop platform base domain target.
KUMOMTA_WEBHOOK_URLhttp://host.docker.internal:8021HTTP address of the kumomta manager service running on the host.

Policy Files Structure

All custom policies are written in Lua and located in apps/backend/kumomta-smtp/:

  • init.lua: Core configuration entrypoint initializing spool partitions, SMTP listeners, and HTTP consoles.
  • policy/constants.lua: Centralized constant parameters (such as delivery thresholds, rate limits, and domains).
  • policy/smtp.lua: Defines ESMTP server authentication rules, HELO/EHLO handshakes, and recipient validation.
  • policy/queue.lua: Governs scheduling policies, backoff wait intervals, retry logic, and queue limits.
  • policy/webhooks.lua: Configures KumoMTA to fire HTTP POST callback streams containing detailed event records back to the kumomta webhook manager service.

Container Development Commands

All container commands must be run from the local/ directory where the Docker Compose file is located:

# Spin up KumoMTA and Mailpit
cd local
docker compose up -d kumomta-smtp reloop-mailpit

# Follow container output logs
docker logs -f kumomta-smtp

# Stop containers and keep volumes intact
docker compose stop kumomta-smtp

Mail Sandbox Interface (Mailpit)

In local development, all emails processed by KumoMTA are safely trapped and rendered inside Mailpit instead of being sent to real inboxes:

  • Open your browser and navigate to http://localhost:8025 to view the Mailpit Web UI.
  • Review outbound HTML layouts, verify compiled dynamic tokens, and audit raw SMTP headers in a sandboxed, zero-risk developer environment.
  • KumoMTA communicates with Mailpit on internal port 1025 inside the Docker network.