KumoMTA and KumoProxy
Deployment Files
Environment File

Environment File

The environment file holds the values that change per deployment: webhook URL, secrets, proxy host, proxy port, proxy egress IP, and EHLO hostname.

Do not put these values directly in init.lua. Keep policy code reviewable and keep secrets in the service manager or secret store.

Where it lives

Install the populated environment file on the KumoMTA host:

/etc/default/kumomta

Use strict ownership and permissions:

sudo chown root:root /etc/default/kumomta
sudo chmod 0600 /etc/default/kumomta

Then configure your KumoMTA service manager to load it as an environment file.

Sanitized template

# Shared token KumoMTA uses when POSTing delivery events back to PING8.
# Generate your own value. Do not reuse the injection bearer token.
PING8_WEBHOOK_TOKEN=<PING8_WEBHOOK_TOKEN>
 
# PING8 event ingest endpoint.
PING8_WEBHOOK_URL=https://app.yourdomain.com/api/kumo/events
 
# KumoProxy host that owns the visible SMTP egress path.
KUMOPROXY_HOST=proxy.yourdomain.com
KUMOPROXY_PORT=5000
KUMOPROXY_PUBLIC_IP=203.0.113.20
KUMOPROXY_HELO=proxy.yourdomain.com

Field guide

VariableRequiredWhat it controls
PING8_WEBHOOK_TOKENYesStatic secret sent with KumoMTA webhook events so PING8 can authenticate the event source.
PING8_WEBHOOK_URLYesPublic HTTPS endpoint where KumoMTA sends delivery, bounce, deferral, complaint, and expiration events.
KUMOPROXY_HOSTYes if using KumoProxyHostname or private IP of the SOCKS5 proxy.
KUMOPROXY_PORTYes if using KumoProxySOCKS5 listener port, commonly 5000.
KUMOPROXY_PUBLIC_IPYes if using KumoProxy source bindingPublic egress IP recipient providers will see. Use a documentation IP here until you replace it.
KUMOPROXY_HELOYesEHLO hostname used by outbound SMTP sessions. It should align with PTR/rDNS expectations.

Injection token is separate

The injection bearer token belongs in the Nginx layer, not in this KumoMTA environment file:

Authorization: Bearer <PING8_INJECTION_TOKEN>

PING8 sends this token when it injects messages. Nginx validates it before forwarding the request to KumoMTA's loopback listener.

Operational checks

After installing the file:

  1. Restart or reload KumoMTA so the variables are visible to policy.
  2. Check service logs for missing required variables.
  3. Confirm the webhook URL is reachable from the KumoMTA host.
  4. Confirm the proxy host and port are reachable from the KumoMTA host.
  5. Confirm no populated secret file is committed to source control.

Common mistakes

  • Reusing the same secret for injection and webhook events.
  • Leaving the populated file world-readable.
  • Forgetting to reload the service after changing values.
  • Setting SPF for the KumoMTA host IP when recipients actually see the KumoProxy egress IP.
  • Setting KUMOPROXY_HELO to a hostname without matching PTR/rDNS.
Deployment FilesNginx Reverse Proxy