KumoMTA setup & configuration

Why does outbound port 25 have to be opened first?

One prerequisite deserves to be settled first because nothing works without it: outbound port 25. It is the port mail servers use to talk to each other — server-to-server transport — while client submission runs on 587 with authentication. Residential lines commonly block it, and the big clouds are not generous either: AWS blocks outbound 25 by default on all instances and requires the "Request to remove email sending limitations" form, with an A record and reverse DNS attached and an answer that typically takes up to a couple of days. Other clouds have similar gates. The direct consequence for anyone deploying an MTA: KumoMTA has to live in a datacenter or cloud where outbound 25 is actually open, with each sending IP carrying a PTR record the receivers can verify. Confirming this — and filing the unblock request early so its lead time runs in parallel with the rest of the preparation — is step one of every deployment we do, because an engine that cannot leave on port 25 simply does not deliver, no matter how well it is configured.

Should KumoMTA run on bare metal, Docker or Kubernetes?

KumoMTA is unusually flexible about its home. The classic route is a repository install on a supported Linux — Rocky and Ubuntu among them — which gives you a systemd service on a machine you control end to end. The project also ships an official Docker container, and the engine's architecture suits Kubernetes well for teams that want their MTA to deploy, scale and roll like the rest of their platform. The honest selection criterion is not benchmark numbers — a single well-configured node moves millions of messages per hour in any of the three — but your operational reality: what your team can patch, monitor and recover confidently. Two technical notes do shape the choice. The spool wants fast local disk because KumoMTA persists messages for durability, so storage-starved containers are a self-inflicted wound. And source IP binding has to be designed deliberately: in containerized and multi-node deployments the clean pattern is to put egress IPs on a proxy speaking the HAProxy protocol — or KumoMTA's own proxy companion — so the addresses, and the reputation attached to them, live independent of any single node. We decide this architecture before installing anything, because redoing it later means moving reputation, and reputation moves badly.

How is KumoMTA configured: init.lua and the helper stack

KumoMTA's defining trait is that its configuration is a program: the policy lives in Lua, executed inside the MTA, which is what gives the engine conditionals, lookups against live data and logic you can version and review like any other code. A production policy does not mean writing everything by hand. The project ships a stack of policy helpers — pre-built modules for shaping, queue management, egress sources, DKIM signing and listener domains — that consume plain TOML files, so the everyday knobs live in readable data files while the Lua glue stays small and stable. Our deployment uses that helper stack deliberately: it keeps your policy close to what the project documents and tests, makes upgrades predictable, and means the person maintaining it in a year reads structured TOML instead of archaeology. We write the policy, comment it, version it in your repository, and validate it with the project's own tooling — there is a shaping validator on the command line precisely so a typo never reaches production. Configuration as code is the feature that makes KumoMTA powerful; treating it with software discipline is what makes it safe.

# Validate shaping rules off-line — a typo never reaches a live queue
$ kumo-tsa-daemon --validate-shaping /opt/kumomta/etc/policy/shaping.toml
shaping.toml: 142 rules parsed · 0 errors · 0 warnings
resolve gmail.com → connection_limit=8 max_message_rate=180/min (community + local)

# What is each provider doing right now? (D=delivered T=transit C=conn Q=queued)
$ kcli queue-summary
SITE                         D      T   C       Q
gmail.com                 4821    132   8       0
outlook.com               3940     61   5      14
yahoo.com                 2104     40   4       0

# Move a poisoned stream onto a healthier queue, rules re-evaluated
$ kcli rebind --domain outlook.com --reason "reputation reset"
rebound 14 messages · TSA rules re-applied

Egress sources and pools: identity by design

What PowerMTA operators know as VirtualMTAs lives in KumoMTA as egress sources and pools: each source is a sending identity — an IP with its EHLO name and behavior — and pools group sources so traffic classes can be routed, throttled and reputed separately. Getting this design right at the start is most of what "scales cleanly" means later. Transactional mail, which recipients expect and open, must not share IPs with bulk promotional traffic whose complaint profile is different; an important brand or customer can earn an isolated pool; a new or risky stream stays quarantined so an incident cannot drag the rest down. The sources helper maps message attributes — campaign, tenant, mail class — to the right pool, so segmentation is enforced by policy instead of by convention. And because sources can bind through a proxy, the same design carries from one node to a cluster without renumbering anything. We dimension the IP count against your real volume — enough addresses that no IP looks aggressive, few enough that each one builds recognizable reputation — and document which stream lives where and why.

Shaping per provider: the rules of each door

Every large mailbox provider has its own tolerances — how many simultaneous connections, how many messages per connection, what hourly pace, when TLS misbehaves — and sending to all of them with one generic policy leaves delivery on the table. KumoMTA expresses these rules in shaping files: sensible global defaults, then per-domain entries that tune connection limits, delivery rates and timeouts to what each receiver actually tolerates. Two things make this layer stronger than hand-rolled throttling. The project maintains community-contributed shaping rules for the major providers, distilled from operators running real volume, which we use as the floor and then adjust to your reputation and mix. And the engine resolves rules per destination with tooling to inspect exactly which policy applies to a given domain, so "what are we doing to this provider right now" has a checkable answer instead of a guess. Shaping is not a set-and-forget table — limits breathe with your reputation — but a deployment that starts from the community baseline, tuned per provider, starts polite. Polite is what new infrastructure needs to be.

What is Traffic Shaping Automation in KumoMTA?

The piece that separates KumoMTA from engines of the previous generation is Traffic Shaping Automation. A standalone daemon watches the responses your traffic receives and adjusts shaping automatically against rules you define: when Gmail starts answering with its rate-limit language at a threshold you set, the rule can drop the message rate for that path for thirty minutes; when a provider returns a block signature, the rule can suspend the queue for two hours instead of hammering a closing door. The community rules ship with patterns for exactly these well-known responses, and your own rules extend them. This is backoff as a first-class, observable system: the automation runs in its own process so it never competes with delivery, it works across a cluster, and every adjustment is explicit policy rather than a hard-coded reflex. We configure TSA in every deployment — daemon, publish/subscribe wiring and rules — because it is the difference between an engine that responds to a provider's frown in seconds and one that waits for a human to read the logs in the morning. The 3 a.m. deferral storm gets handled at 3 a.m.; you read about it at 9.

What DNS and authentication does KumoMTA need before sending?

Before the first message leaves, DNS and authentication have to be finished, because this is where delivery against Gmail, Yahoo and Microsoft is won or lost in 2026. Every sending IP needs its PTR record resolving to a name coherent with your sending domain — an IP without reverse DNS is an immediate red flag. The domain publishes SPF that covers the sending sources without blowing the ten-lookup limit, DKIM keys that KumoMTA's signing helper applies per domain on every message, and a DMARC record that aligns through SPF or DKIM. Alignment is the detail that fells otherwise correct deployments: it is not enough that SPF and DKIM pass — the domain that passes has to match the one recipients see in the From. We close and verify this layer before the warm-up begins, including the boring confirmations people skip: that forwarding does not break signatures where you can help it, that the DMARC policy has a path from monitoring toward enforcement, and that every stream the policy signs is one you actually send. A perfect engine sending mail that bounces on half-built authentication is the most preventable failure in this business.

How long does KumoMTA IP warm-up take?

New IPs have no reputation, and providers distrust strangers who appear at volume — so the deployment includes a written warm-up plan, never an afterthought. The mechanics are unglamorous and they work: start with modest daily numbers per IP and per provider, multiply in steps over four to eight weeks, send first to your most engaged recipients so the early signals say this mail is wanted, and let the providers' responses govern the pace rather than a rigid calendar. KumoMTA gives the warm-up two structural advantages. Shaping expresses the ramp as explicit per-provider limits instead of campaign-side discipline that someone forgets under pressure. And TSA acts as the safety rail: if a step triggers deferrals or a complaint uptick, automation slows that path immediately while the plan pauses and recovers. Skipping or rushing this phase is the single most common reason technically perfect deployments deliver poorly for their first months. We would rather hand you a slightly slower start and a reputation that holds — and we put that trade in writing on day one, so nobody is surprised that week two is not full volume.

Bounces, feedback loops and suppression from day one

Healthy sending shows in how it handles what comes back, and that machinery is configured before the first campaign, not after the first scare. KumoMTA classifies responses with a rich bounce taxonomy; we wire it so hard bounces — addresses that do not exist — are suppressed immediately and never retried, soft failures retry with sane patience, and policy blocks are treated with the long intervals they deserve. Feedback loops with the providers that offer them are registered so complaint events flow back automatically, and every complainer lands on the suppression list without a human in the loop. Insisting on dead or unwilling addresses is among the fastest ways to teach providers you are careless; a deployment that suppresses ruthlessly from day one reads as a serious sender from its first week. The suppression list is also where compliance becomes concrete: unsubscribes honored within the windows the bulk-sender rules demand, and the 0.30% complaint line — the threshold where providers act regardless of your authentication — kept at a respectful distance by list discipline rather than by luck.

Logs, accounting and out-of-band webhooks

Everything the engine does leaves a trace, and KumoMTA's logging is built for the volumes where traces get expensive: structured records written as compressed JSONL segments, with the fields, rotation and retention under your control. Recent releases added a module for reading and writing those segments directly, which unlocks a deployment pattern we like a lot for serious operations: webhook and analytics processing running out of band, as a separate long-lived process with its own checkpointing, retries and failure modes, instead of riding inside the MTA's hot path. Your platform learns in near-real time what delivered, deferred and bounced — without log shipping ever being able to slow delivery down. We design this layer in the deployment: which events are recorded at what detail, how long segments are retained before deletion or anonymization in line with the privacy law that applies to you, and how the data reaches your dashboards. An engine without visibility eventually surprises you; this one is built to be watched, and we leave it watchable.

Integration: SMTP, HTTP API and your stack

KumoMTA is the infrastructure layer, and it meets your application where it already is. The classic path is SMTP injection from your campaign or application tier, accepted on a listener you control and routed by policy. Alongside it there is a native HTTP injection API for systems that would rather speak JSON to an endpoint than maintain an SMTP client, which also makes the engine pleasant to use from serverless and queue-driven producers. Outbound, the event stream feeds webhooks for delivery state, and the engine connects to the ecosystem a modern platform expects — message queues like AMQP and Kafka for event transport, Prometheus metrics with Grafana dashboards for operations, secrets kept in a vault rather than in config files, and direct data lookups from policy when routing decisions need live answers. We design the injection and event paths explicitly: what enters where, authenticated how, and which events your systems consume. Done right, the MTA stops being a black box at the edge of the diagram and becomes an ordinary, observable piece of your platform.

Security: access control, relay discipline and TLS

A sending engine is an attractive target, and KumoMTA gives a deployment modern primitives to lock it down — recent releases added a full authentication, authorization and accounting framework, with granular control and an audit trail over every interaction with the engine's APIs. We use it. Injection listeners accept mail only from authenticated, enumerated sources, so the classic open-relay disaster is structurally off the table; the HTTP API and metrics endpoints answer only to trusted networks; TLS is required where mail and credentials move; and the DKIM private keys live with the file permissions and rotation discipline of any production secret. Around the engine, the usual hardening applies — minimal services, firewalling, patched OS — and the audit trail means "who touched what" has an answer. A compromised or permissive MTA does not just embarrass you; it spends your IP reputation on someone else's spam and lands you on blocklists within hours. This layer rarely makes the demo, which is exactly why we refuse to treat it as optional.

Data retention and the law that applies to you

Delivery logs are personal data with a clock on them. Accounting records carry recipient addresses and behavior, which makes retention a legal design decision, not a disk-space one: under the GDPR in Europe — and its cousins elsewhere — you keep what you need for as long as you can justify, then delete or anonymize on schedule. The deployment sets this from the start: which fields are recorded, how segments rotate so detail never fills the disk, and a written retention policy the rotation actually enforces. The same forethought covers consent: we build sending infrastructure for permission-based programs only, with suppression lists that make opt-outs stick, because no engine configuration rescues a sender mailing people who never asked. If your market adds rules of its own — one-click unsubscribe windows, sector regulations, regional codes — the policy encodes them rather than trusting someone to remember. Compliance designed in is cheap; compliance retrofitted under complaint pressure is not.

Scaling and high availability

One well-built node carries an enormous load, but growth and fault tolerance are designed, not improvised. KumoMTA clusters cleanly: multiple kumod nodes share traffic, the shaping automation daemon can run as its own small sub-cluster so log traffic never meshes across every node, shared state like throttles can live in Redis, and egress IPs bound through a proxy survive any single node's failure with their reputation intact instead of frozen on a dead machine. The pattern we deploy keeps every node's configuration identical — same policy, same shaping, source selection by pool — so adding capacity is provisioning, not surgery. Even when you start on a single server, we leave these seams in place: the proxy in front of the IPs, the policy in version control, the TSA wiring cluster-ready. The expensive version of scaling is the one where reputation has to move; the cheap version is the one where the architecture already had room. Day one is when that choice costs the least.

Does KumoMTA come with a control panel?

KumoMTA has no web UI, and that is a deliberate design position: the project treats configuration as code and operations as APIs, metrics and tooling, not clicks. For many engineering teams that is exactly right. For operations that want a visual layer — queues at a glance, per-provider delivery state, an interface a non-operator can read — we build a control panel on top of KumoMTA without compromising the code-first model underneath: the panel observes and instructs through the same APIs your automation uses, so there is never a second source of truth. During the deployment we set up the operational baseline either way — dashboards, alerts on deferrals, rejections and spam-trap signals, queue visibility — because a panel is optional but observability is not.

Should it even be KumoMTA?

The honest question before deploying is whether KumoMTA is the right engine for you, and our answer is allowed to be no. Its sweet spot is real outbound volume with a need for fine control per provider and per IP, owned infrastructure, and a team — yours or ours — that treats the MTA as a production system. For modest volumes, a well-tuned conventional MTA or a cloud relay covers the case with less surface to operate. If you already run PowerMTA happily under license, the move is a calculation, not a reflex — we lay that math out in the migration page and we are equally comfortable with either outcome. And when the field is genuinely open — KumoMTA, PowerMTA, Halon, MailerQ — we treat it as an MTA selection exercise with your interest in front, because we do not resell any of them. The cheapest deployment is the one you did not need; we would rather tell you that than build it.

What "done" looks like

A deployment is done when it sustains itself and is understood without us. Concretely: the IPs are warming on a written plan at a healthy pace; DNS and authentication pass and align for every stream; sources and pools separate mail by nature, with shaping per provider starting from the community baseline and tuned to yours; TSA reacts to provider pushback automatically and visibly; bounces are processed, dead addresses suppress themselves, feedback loops are wired; logs flow to your dashboards with retention enforced; access control and TLS are on, with an audit trail behind the APIs. And everything is documented — how it is built, why each decision was made, what to touch when something changes — with the policy in version control. A deployment that only works while its builder is reachable is not done; it is a handover that has not happened yet. We consider the project closed when your team, or our managed service, can run it without folklore.

How does a KumoMTA deployment unfold, step by step?

We start with the free 25-point audit, which confirms the engine fits and fixes the starting state of DNS, IPs and authentication. From there the work follows the order this page describes: confirm outbound port 25 and file the cloud unblock early; prepare and harden the host — or the container platform — and decide the IP-binding architecture; close DNS, authentication and alignment; install from the repo or container and lay down the policy with the helper stack; design sources, pools and per-provider shaping from the community baseline; wire Traffic Shaping Automation and validate every shaping file with the project tooling; connect bounce processing, feedback loops, suppression and monitoring; write the warm-up plan; then start the ramp under daily watch. Preparation and configuration typically take days to a couple of weeks depending on your environment, with the port-25 lead time running alongside; the warm-up then adds four to eight weeks to target volume with a reputation that holds. At close, you get the installation documented for your team to run — or we keep operating it as managed KumoMTA. The infrastructure is yours throughout, and the relationship bills for work, with no engine being sold across the table.

If you are planning a KumoMTA deployment — first MTA, new capacity, or a rebuild of something that never quite worked — the starting point costs nothing: the 25-point audit confirms the fit and the state of your DNS, IPs and authentication before anything is built. From there, we deploy it the way we run our own: shaped, warmed, watched and written down.