KumoMTA Logs Setup

The KumoMTA Webhook Service is an ElysiaJS microservice that processes delivery logs, hard bounces, soft bounces, spam complaints, and feedback loops emitted by the KumoMTA mail server. It indexes delivery receipts, enabling Reloop to track real-time delivery performance metrics.

Prerequisite First

Before starting the KumoMTA Webhook Service, make sure you've completed the base Local Development Setup (installed Bun, configured the hosts file, and started the Docker container stack).

Quick Start

Dependencies are handled globally at the root directory. You can start the KumoMTA Webhook Service development server instantly:

# Start the dev server with hot reloading
bun be:kumomta:dev

cd apps/backend/kumomta
bun dev

Once running, the KumoMTA Webhook Service will listen locally on port 8021. You can query it via Caddy at https://local.reloop.sh/api/kumomta 🎉

Service Information

Directory Location: apps/backend/kumomta/
Local Listening Port: 8021 (configurable with PORT env variable)
Unified Access Route: https://local.reloop.sh/api/kumomta
Primary Tech Stack: ElysiaJS, PostgreSQL, Redis, NATS
Dependencies: Relies on PostgreSQL (to record transaction history) and NATS (to broadcast bounce and delivery event buses).

Environment Configuration

The KumoMTA Webhook Service environment variables are defined in apps/backend/kumomta/.env. If you ran bun env:setup at the root, your .env is already configured:

# Database & Cache Configurations
PG_URL=postgresql://reloop:reloop123@localhost:5432/reloop
REDIS_URL=redis://:reloop123@localhost:6379

# Server Gateway Configuration
PORT=8021
NODE_ENV=development
X_KUMOMTA_KEY=reloop

# Event Bus Broker
NATS_URL=nats://localhost:4222

Reference Table

Variable	Required	Default Value	Description
`PG_URL`	YES	`postgresql://...`	PostgreSQL database connection string.
`REDIS_URL`	YES	`redis://...`	Redis connection URL for temporary log lookups.
`PORT`	YES	`8021`	Local port number the Elysia app listens to on the host.
`X_KUMOMTA_KEY`	YES	`reloop`	Security key token (`x-kumomta-key` header) used to authenticate webhook streams coming from KumoMTA.
`NATS_URL`	YES	`nats://localhost:4222`	Connection URL for NATS event bus messaging.
`NODE_ENV`	YES	`development`	Active environment scope (`development` or `production`).

Development Commands

All workspace operations should be executed from the monorepo root directory using Turborepo filters:

Command	Action	Scope
`bun be:kumomta:dev`	Start the KumoMTA dev server with hot reloading	Development
`bun run --filter=kumomta build`	Compile the KumoMTA service for production	Production
`bun run --filter=kumomta start`	Run the compiled production build locally	Production
`bun run --filter=kumomta check-types`	Verify TypeScript type-safety	Code Quality

Database Schema & Relationships

The KumoMTA Webhook Service listens to high-throughput HTTP logging callbacks from the SMTP MTA engine and persists real-time updates directly into PostgreSQL.

Relational Tables Mapped

email_log: Updates the active sending log's status (from pending to delivered or bounced) and records the deliveredAt or failedAt timestamps (see Email Service Schema).
email_event: Chronologically archives granular SMTP events (e.g. soft-bounce retry codes or hard-bounce details) linked directly to the main email_log (see Email Service Schema).

Interactive API Docs (Swagger)

The KumoMTA Webhook Service publishes dynamic Swagger documentation directly from ElysiaJS. To test endpoints and query API structures:

Open your browser and navigate to the interactive Swagger playground at https://local.reloop.sh/api/kumomta/openapi (or http://localhost:8021/api/kumomta/openapi directly).
Use the interactive Swagger UI playground to run queries and inspect request schemas.

Integration with SMTP Servers

When KumoMTA processes or fails to deliver an email:

It executes webhook hooks configured inside the local kumomta-smtp Lua script routines.
It sends an HTTP POST callback containing extensive event logs (recipient details, bounce type, MX SMTP responses) to https://local.reloop.sh/api/kumomta/webhook.
The KumoMTA Webhook Service validates the x-kumomta-key authorization token header.
Payload details are parsed and ingested into ClickHouse/PostgreSQL, publishing real-time notification streams over NATS under kumomta.event.* topics.