KumoMTA and KumoProxy
Deployment Files
Overview

Deployment Files

This section explains how to adapt the KumoMTA deployment files used by a working PING8 integration into your own self-hosted environment.

Use these pages as an operator guide, not as a place to paste production secrets. Keep all real tokens, hostnames, and IP addresses in your own secure deployment system.

File map

File patternInstall onTypical locationPurpose
env.exampleKumoMTA host/etc/default/kumomtaRuntime secrets and host-specific values loaded by the service manager.
nginx.confKumoMTA host/etc/nginx/conf.d/mta.yourdomain.com.confTLS termination, bearer auth, injection proxying, metrics proxying, and default deny behavior.
init.luaKumoMTA host/opt/kumomta/etc/policy/init.luaKumoMTA policy: HTTP listener, spool, egress pool, KumoProxy routing, queues, and webhook events.
KumoProxy serviceKumoProxy hostsystemd service or equivalentSOCKS5 egress process that owns the public sending IP path.

Reference topology

PING8 app
  https://app.yourdomain.com
        |
        | HTTPS POST /api/inject/v1
        v
KumoMTA reverse proxy
  https://mta.yourdomain.com
        |
        | HTTP on loopback
        v
KumoMTA HTTP listener
  127.0.0.1:8000
        |
        | SOCKS5
        v
KumoProxy egress
  proxy.yourdomain.com:5000
        |
        | SMTP TCP/25
        v
Recipient mailbox providers

This shape keeps public TLS and authentication in Nginx, keeps KumoMTA's HTTP listener private to localhost, and lets KumoProxy control the outbound SMTP source IP that recipient providers see.

Secret separation

Use two different secrets:

SecretUsed byDirectionPurpose
<PING8_INJECTION_TOKEN>PING8 and NginxPING8 -> KumoMTAAllows PING8 to inject messages through /api/inject/v1.
<PING8_WEBHOOK_TOKEN>KumoMTA and PING8KumoMTA -> PING8Allows KumoMTA delivery events to be accepted by PING8.

Never reuse the injection token as the webhook token. Rotating one should not require rotating the other.

Rollout order

  1. Prepare DNS for mta.yourdomain.com and proxy.yourdomain.com.
  2. Install KumoMTA on the MTA host.
  3. Install KumoProxy on the egress host if you need separate egress.
  4. Create the environment file with placeholder values replaced.
  5. Install init.lua and validate KumoMTA starts.
  6. Install Nginx, issue TLS, and lock down /api/inject/v1 and /metrics.
  7. Configure PING8 with sending disabled.
  8. Run the PING8 connection test.
  9. Send one owned test message.
  10. Confirm webhook lifecycle events appear in PING8.
  11. Increase volume gradually using a warmup plan.

Related pages

DNS and TLSEnvironment File