Beginner’s Guide: Getting Started with KumoMTA

Sergey Syerkin,

KumoMTA is a modern, high-performance Mail Transfer Agent built for flexibility, throughput, and automation. Whether you’re launching your first SMTP service or migrating from another MTA, this guide walks you through installing KumoMTA, setting up your first basic configuration, and applying real-world sending throttles per domain like Gmail or Yahoo plus dynamic shaping based on bounce patterns.

📚 Official Documentation: https://docs.kumomta.com/userguide

1. Installing KumoMTA

Follow the official Quickstart instructions:

curl -fsSL https://get.kumomta.com/install.sh | bash

After installation:

systemctl enable kumod
systemctl start kumod

Validate the configuration:

/opt/kumomta/sbin/kumod --validate

2. Basic Configuration (init.lua)

Create /opt/kumomta/etc/policy/init.lua with:

local kumo = require 'kumo'

kumo.on('init', function()
  kumo.define_spool('/var/spool/kumod')
  kumo.configure_local_logs({log_dir='/var/log/kumod'})
end)

kumo.on('get_egress_path_config', function(domain, egress_source, site_name)
  return kumo.make_egress_path {
    enable_tls = 'Opportunistic'
  }
end)

Restart to apply:

systemctl restart kumod

3. Attaching an IP Address for Outgoing Mail

In init.lua, update the make_egress_path section to define the IP:

kumo.on('get_egress_path_config', function(domain, egress_source, site_name)
  return kumo.make_egress_path {
    source_ip = '192.0.2.100',
    enable_tls = 'Opportunistic'
  }
end)

This will ensure KumoMTA uses the specific IP for sending outbound email.

4. Throttling by Domain: e.g. Gmail, Yahoo

Create a file: /opt/kumomta/etc/policy/shaping_custom.toml

["gmail.com"]
connection_limit = 5
max_deliveries_per_connection = 20
max_connection_rate = "60/min"
enable_tls = "Required"

["yahoo.com"]
connection_limit = 3
max_deliveries_per_connection = 10
max_connection_rate = "30/min"
enable_tls = "Required"

Validate:

/opt/kumomta/sbin/validate-shaping shaping_custom.toml

5. Enabling Bounce-Based Automation (TSA)

In /opt/kumomta/etc/policy/shaping_custom.toml:

[provider."gmail"]
match = [{MXSuffix=".google.com"}]
automation = [
  { regex = "5\\.5\\.0 .* rate too high", action = "Suspend", duration = "1h" },
  { regex = "quota exceeded", action = { SetConfig={name="max_connection_rate",value="10/min"} }, trigger={Threshold="3/hr"}, duration="2h" }
]

Then in /opt/kumomta/etc/policy/tsa_init.lua:

local tsa = require 'tsa'
local kumo = require 'kumo'

kumo.on('tsa_init', function()
  tsa.start_http_listener {
    listen = '0.0.0.0:8008',
    trusted_hosts = {'127.0.0.1', '::1'}
  }
end)

Start TSA:

systemctl enable --now kumo-tsa-daemon

6. Sending a Test Email

Use the KumoMTA test client utility:

kcli inject --from [email protected] --to [email protected] --subject "Test from KumoMTA" --body "Hello! This is a test email."

You can check the delivery logs to verify the message:

tail -f /var/log/kumod/egress.log

Do not forget about Authentication Essentials: SPF, DKIM, DMARC

To achieve proper email deliverability and pass authentication checks, ensure the following:

SPF (Sender Policy Framework)

  • Add a TXT record in your domain’s DNS:
example: v=spf1 ip4:192.0.2.100 -all

This authorizes the IP used by KumoMTA to send email on behalf of your domain.

DKIM (DomainKeys Identified Mail)

  • Generate DKIM keys using opendkim or another signer.
  • Publish your public key in DNS:
example: selector._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqh..."
  • Configure your signing in KumoMTA (via Lua hook or use external signing proxy).

DMARC (Domain-based Message Authentication)

  • Add a DNS record:
example: _dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:[email protected]"
  • Adjust p= to quarantine or reject once you’re confident.

📌 Additional Best Practices

  • Ensure reverse DNS (PTR) matches the hostname.
  • Use a consistent HELO/EHLO hostname (set via init.lua).
  • Monitor Postmaster Tools from Gmail & Microsoft.
  • Add List-Unsubscribe headers.

📤 Send a Test Email After Configuration

Once SPF, DKIM, and DMARC are properly configured:

kcli inject --from [email protected] --to [email protected] --subject "Authentication Test" --body "This is a test email with SPF, DKIM, and DMARC configured."

You can then verify headers using your Gmail email address or use our free audit tool https://emailconsul.com/audit

🧪 7. Monitoring and Testing

  • Validate main config: kumod --validate
  • Validate shaping: validate-shaping shaping_custom.toml
  • Log path: /var/log/kumod/
  • Test bounce triggers: /var/log/kumo-tsa-daemon.log
  • Real-time tracing: kcli trace-smtp-client

If you have any questions or need help getting started, feel free to reach out to EmailConsul.

EmailConsul offers seamless integration with KumoMTA, providing smarter monitoring, real-time visibility, and analytics tailored to improve your deliverability performance and infrastructure insight.

Infrastructure & Security