/ Infrastructure · Migration playbook
Migrating from PowerMTA to KumoMTA: a four-phase operational guide.
A working playbook for moving a production PowerMTA deployment to KumoMTA without burning reputation, dropping deliverability, or running out of rollback options. Covers the four phases, the configuration translation with code side by side, the dual-send strategy, and the validation checks that confirm a clean cutover.
In short
A production PowerMTA to KumoMTA migration is an eight-week project for a typical deployment with established sender reputation. It runs in four phases: planning and provisioning (weeks one to two), configuration translation (weeks two to three), dual-send validation with traffic ramping per receiver (weeks three to six), and cutover plus decommission (weeks six to eight). No automated conversion tool exists because the configuration paradigms differ fundamentally. Dedicated IPs do not need re-warming because reputation lives on the IP, not on the software. The riskier the existing reputation, the longer the dual-send window should be.
-
8 weeks
Typical duration for a production migration with established sender reputation. Greenfield is faster; complex multi-tenant is longer.
-
No tool
There is no automated PowerMTA to KumoMTA conversion utility. Translation is conceptual, performed by a deliverability engineer deliberately.
-
No re-warm
Sender reputation lives on the IP and domain, not on the MTA software. Keeping the same IPs means no warming period is required.
-
Dual-send
Running both MTAs in parallel during the validation window is the standard pattern and what makes the migration defensible.
/ 01 — Before you start
Pre-checks that decide whether the migration succeeds.
Most failed MTA migrations fail because of something visible weeks before the cutover that nobody acted on. The pre-checks below catch the failures early when they are cheap to fix.
Capacity
Target servers provisioned and isolated
KumoMTA target nodes run on Linux only — Rocky 9, Alma 9, RHEL 9, or Ubuntu LTS are the common picks. Four CPU cores minimum for production per the KumoMTA team. Same network egress as PowerMTA. Do not co-locate KumoMTA on the same servers as PowerMTA during the dual-send window: file descriptor budgets, port binding, and queue spool paths will collide.
Team readiness
At least one Lua-comfortable engineer
KumoMTA policy is expressed as Lua, not as configuration directives. Migrations led by teams without anyone comfortable in Lua tend to stall in phase two. Two weeks of Lua exposure before the project starts is enough; expecting to learn during the migration extends the timeline materially.
Reputation baseline
Postmaster Tools, SNDS, and Yahoo Insights captured
Capture two weeks of receiver-side reputation data before any traffic shifts. Without that baseline, distinguishing migration effects from normal week-to-week variance becomes impossible. SNDS color codes, Gmail domain reputation, and Yahoo Insights complaint rates are the minimum capture set.
Timing
Not during peak season
Ecommerce should not migrate during the October-to-January peak. SaaS should not migrate immediately before a major product launch. The dual-send window introduces operational complexity that any incident during peak makes worse. February through September is the usual window for the senders we work with.
Observability
Prometheus and Grafana wired before traffic flows
KumoMTA exposes Prometheus metrics natively and the team publishes an official Grafana dashboard on grafana.com. Configure both before any mail leaves the new MTA. You cannot debug what you cannot see, and the dual-send validation depends on comparing per-receiver metrics in real time.
Rollback
PowerMTA license retention plan
Keep the PowerMTA license active for at least two weeks past the cutover. License renewals or terminations executed prematurely turn a recoverable incident into a vendor conversation. Coordinate with procurement on the timing before the project begins.
/ 02 — Vocabulary
How PowerMTA concepts map to KumoMTA concepts.
The translation table below covers the abstractions a deliverability engineer reaches for daily. The mapping is mostly clean because KumoMTA was designed by people who knew PowerMTA, and many of the choices were deliberate modernizations of familiar primitives. Where the mapping is fuzzy, the notes column explains why.
| PowerMTA | KumoMTA | Notes |
|---|---|---|
| virtual-mta (VMTA) | Egress Source + Egress Pool | Source binds the IP, pool groups sources for selection. Tenant-level isolation becomes a first-class primitive rather than a naming convention. |
| domain stanza | shaping_custom.toml entries | Per-domain throttling moves out of the main config into declarative TOML. Reload without restart is supported. |
| domain-key (DKIM) | DKIM helper config | Signing policy expressed declaratively. Secondary signing handled by the additional_signatures array. |
| mx-rollup directive | native (no config) | KumoMTA performs MX rollup automatically. The manual configuration tables PowerMTA users maintain disappear. |
| smtp-pattern-list backoff | automation array in TOML | Regex-triggered actions on receiver responses. Cluster-aware — throttles can be shared across nodes without manual division. |
| PowerMTA Management Console | Grafana + Prometheus | Operational visibility moves from a vendor-bundled dashboard to the open observability stack you already run for everything else. |
| accounting files (CSV) | webhooks + Kafka + AMQP | Event stream rather than file polling. Real-time consumption replaces the batch processing model. |
| pmtactl | kcli + tailer | Admin CLI for injection, queue inspection, log following. The mental model carries over; flags and arguments differ. |
| smtp-source-host | source_address in Lua | Source IP binding becomes a property of the Egress Source rather than a per-VMTA directive. |
| macros / $variable | Lua functions and iteration | Imperative scripting replaces config-time substitution. Significantly more powerful and less fragile at scale. |
/ 03 — Phases
What does each migration phase actually involve?
The four phases below assume a production deployment with established sender reputation. Greenfield migrations compress phases one and two and skip dual-send entirely. The timeline shown is the typical lower bound for production work; complex multi-tenant migrations stretch to twelve weeks or more.
Phase 1 · Weeks 1–2
Planning and provisioning
Inventory every VMTA, domain rule, DKIM key, and accounting integration in the existing PowerMTA deployment. Map dedicated IPs by stream and by tenant. Provision KumoMTA target servers in the same network egress, with the same IP allocations available for binding when needed. Set up Prometheus, Grafana, and the event consumer pipeline before any mail flows.
Output: a spreadsheet or document that lists every configurable behavior of the current PowerMTA cluster and the KumoMTA equivalent that will replace it. Without this document, phase two devolves into archaeology.
Phase 2 · Weeks 2–3
Configuration translation
Translate the inventory from phase one into KumoMTA config. Egress Sources for each dedicated IP. Egress Pools grouping sources by stream and tenant. Shaping TOML for per-domain throttles. DKIM helper config for all signing identities. Lua event handlers for any per-message logic that lived in PMTA macros.
Validate each piece in isolation before integrating. KumoMTA's kcli inject command sends test messages without touching production traffic. Use it relentlessly.
Phase 3 · Weeks 3–6
Dual-send and validation
Both MTAs are operational. Production traffic flows through both paths. Begin with five to ten percent of one stream routed through KumoMTA, with the rest staying on PowerMTA. Compare receiver-side metrics daily: bounce rates, complaint rates, Postmaster Tools reputation, SNDS color codes, Yahoo Insights placement signals. Ramp the percentage per receiver as the data converges.
This is the phase that turns a risky migration into a defensible one. The duration is variable — three weeks is the minimum for a sender with strong existing reputation, four to six weeks is normal for high-volume multi-tenant deployments.
Phase 4 · Weeks 6–8
Cutover and decommission
Once every receiver has held stable on KumoMTA for at least one week at one hundred percent traffic, the cutover is complete. PowerMTA stays available for at least two weeks as a hot fallback, then is gradually drained and shut down. License decommission happens after the fallback window closes, not before.
Output: PowerMTA archived but not deleted, KumoMTA carrying production load, monitoring confirms reputation and bounce rates stable, the team has at least two weeks of operational data on the new platform.
/ Interactive — the cutover dial
A dial, not a switch.
\u2014
Phase
\u2014
What you validate here
\u2014
The risk
\u2014
The phase boundaries are a guide, not a rule \u2014 move in the steps your reputation and metrics justify. The constant across every phase: keep PowerMTA able to take the load back until the hold period proves you don't need it.
/ 04 — Translation
The same configuration in PowerMTA and KumoMTA, side by side.
Five common configuration patterns translated from PowerMTA to KumoMTA. Read the left column as what your team has today, the right column as what they will write next.
1. Virtual MTA → Egress Source + Pool
PowerMTA · /etc/pmta/config
<virtual-mta acme-tx-01>
smtp-source-host 192.0.2.50 mta1.acme.io
smtp-source-port 25
max-smtp-out 200
process-x-virtual-mta no
</virtual-mta>
<virtual-mta-pool acme-transactional>
virtual-mta acme-tx-01
</virtual-mta-pool>KumoMTA · init.lua
kumo.on("init", function()
kumo.define_egress_source {
name = "acme-tx-01",
source_address = "192.0.2.50",
ehlo_domain = "mta1.acme.io",
}
kumo.define_egress_pool {
name = "acme-transactional",
entries = { { name = "acme-tx-01" } },
}
end)2. Per-domain throttling
PowerMTA · /etc/pmta/config
<domain gmail.com>
max-smtp-out 100
max-msg-rate 100/min
max-connect-rate 20/min
use-starttls true
require-starttls true
</domain>
<domain *yahoo.com>
max-smtp-out 50
max-msg-rate 50/min
use-starttls true
</domain>KumoMTA · shaping_custom.toml
["gmail.com"]
connection_limit = 100
max_message_rate = "100/min"
max_connection_rate = "20/min"
enable_tls = "Required"
["yahoo.com"]
connection_limit = 50
max_message_rate = "50/min"
enable_tls = "Opportunistic"3. DKIM signing with secondary signature
PowerMTA · DKIM stanza
<source 0/0>
process-x-dkim-options yes
<source>
<domain *>
second-dkim-sign yes
second-dkim-identity @platform.acme.io
</domain>
domain-key dk1024, example.com,
/etc/pmta/dkim/example.com.pem
</source>
</source>KumoMTA · DKIM helper TOML
[domain.'example.com']
selector = 'dk1024'
filename = '/opt/kumomta/dkim/example.com.pem'
policy = 'SignAlways'
additional_signatures = ["AcmePlatform"]
[signature."AcmePlatform"]
policy = "Always"
domain = "platform.acme.io"
selector = "dk1024"4. Receiver-triggered backoff
PowerMTA · smtp-pattern-list
<smtp-pattern-list ms-backoff>
reply /try again later/ mode=backoff
reply /rate limit/ mode=backoff
</smtp-pattern-list>
<domain hotmail.com>
smtp-pattern-list ms-backoff
</domain>
<domain outlook.com>
smtp-pattern-list ms-backoff
</domain>KumoMTA · shaping_custom.toml
[provider."microsoft"]
match = [{MXSuffix=".olc.protection.outlook.com"}]
automation = [
{ regex = "try again later",
action = "Suspend",
duration = "1h" },
{ regex = "rate limit",
action = { SetConfig = {
name="max_message_rate",
value="10/min" } },
duration = "2h" }
]5. SMTP listener on multiple ports
PowerMTA · global config
smtp-listener 0.0.0.0:2525
smtp-listener 0.0.0.0:2530
smtp-listener 0.0.0.0:2535
smtp-listener 0.0.0.0:2540
smtp-listener 0.0.0.0:2545
smtp-tls-key /etc/ssl/edp/privkey.pem
smtp-tls-cert /etc/ssl/edp/fullchain.pemKumoMTA · init.lua with iteration
-- Iteration replaces five repeated stanzas
for _, port in ipairs {2525, 2530, 2535, 2540, 2545} do
kumo.start_esmtp_listener {
listen = "0.0.0.0:" .. port,
tls_certificate = "/etc/ssl/edp/fullchain.pem",
tls_private_key = "/etc/ssl/edp/privkey.pem",
}
end/ 05 — Strategy
How do you run both MTAs in parallel safely?
The dual-send window is the most operationally interesting part of the migration and the most often skipped by teams under pressure. Skipping it means the cutover is a leap of faith; running it means the cutover is a formality.
Where the split lives
The decision of which MTA handles a given message has to live in your application layer or in a router between the application and the MTAs. PowerMTA and KumoMTA do not coordinate with each other; the split is yours to design.
The most common pattern is a hash-based split on a stable message attribute — recipient domain, tenant ID, or message-id modulo a percentage threshold. The percentage is stored in a config that operations can change without a deploy. Begin at five percent for the first receiver, hold a week, raise to twenty-five, hold, raise to fifty, hold, raise to one hundred. Move to the next receiver only when the previous one is stable at one hundred.
What to measure
The signals you compare daily between the PowerMTA path and the KumoMTA path:
- Bounce rate by receiver, with hard and soft separated
- Complaint rate by receiver
- Deferred-then-delivered ratio (proxy for receiver-side throttling)
- Postmaster Tools domain and IP reputation, captured daily
- SNDS color codes for Outlook properties
- Yahoo Insights placement signals where available
- Queue depth and connection error rates per MTA
Ramp template
For Gmail specifically, the ramp template the team uses is: week 3 at five percent KumoMTA, week 4 at twenty-five percent, week 5 at fifty percent, week 6 at one hundred. Holding a full week at each level catches receiver-side reputation drift before it becomes a placement collapse. Yahoo, Microsoft, and Apple each get their own four-week ramp running in parallel once Gmail crosses fifty percent successfully.
/ 06 — Pitfalls
What goes wrong, and how to recognize it before it becomes an incident.
The pitfalls below come from migrations we have either led, advised on, or read post-mortems of. Each one has a recognizable early signal that the right monitoring catches before placement degrades.
Pitfall 1 · DKIM key mismatch after migration
Symptom: messages sent through KumoMTA fail DKIM verification at the receiver, bounce rate spikes on Gmail and Yahoo within hours. Cause: the DKIM private key file path in KumoMTA's helper config points to a key that does not match the public key published in DNS, or the selector name differs. Detection: use opendkim-testkey against your DNS records before any traffic flows, and inspect the first ten messages sent through KumoMTA with full headers to confirm signatures match.
Pitfall 2 · MX rollup behavior change for white-label receivers
Symptom: per-domain throttles you tuned for a custom MX cluster stop firing because KumoMTA rolled them up under a parent MX. Cause: PowerMTA required explicit MX rollup configuration; KumoMTA does it automatically based on MX records. White-label mailbox providers using parent infrastructure are now throttled at the MX level, not the domain level. Detection: query kcli to inspect which queues messages are being assigned to and confirm the throttle scope matches your intent.
Pitfall 3 · Event consumer cannot keep up with webhook volume
Symptom: bounce processing falls behind, suppression list updates lag, complaints take hours to register. Cause: PowerMTA's accounting files were polled on a schedule; KumoMTA pushes events in real time. The downstream consumer needs to handle a higher event rate, often with bursts. Detection: instrument the consumer with end-to-end latency tracking from message send to event processed. If p99 latency exceeds five minutes during dual-send, the consumer needs more workers or a buffering layer like Kafka.
Pitfall 4 · Source IP binding fails silently for new pools
Symptom: messages leave KumoMTA from the wrong source IP, causing SPF failures or reputation crossover between tenants. Cause: the Egress Source source_address was misconfigured, or the host's network interface does not have the IP assigned. Detection: for every Egress Source in the new config, send a test message and inspect the received headers at a controlled mailbox to confirm the source IP. Do this before any production traffic flows.
Pitfall 5 · PowerMTA decommissioned too early
Symptom: a deliverability incident emerges on week three post-cutover and rollback is no longer possible because the PowerMTA cluster has been turned off and the license terminated. Cause: procurement pressure or operational tidiness shut down PowerMTA too soon. Detection: codify the rollback retention in writing before the migration starts. Two weeks past cutover is the absolute minimum; four weeks is what we recommend.
/ 07 — Validation
How do you confirm the migration succeeded?
Day 1 post-cutover
Operational stability checks
- Queue depth stable, not growing
- Connection error rate under one percent
- Source IPs match expected configuration
- DKIM signatures verifying at receiver
- Webhook consumer keeping pace with events
Week 1 post-cutover
Reputation signals settled
- Postmaster Tools reputation unchanged or improved
- SNDS color codes green across all sending IPs
- Yahoo Insights complaint rates stable
- Bounce rate within one percent of pre-migration baseline
- No new entries on major blocklists
Month 1 post-cutover
Business metrics confirm
- Open rates within normal variance
- Click rates within normal variance
- Customer-reported deliverability incidents not elevated
- PowerMTA fully decommissioned, license terminated
- Team comfortable operating KumoMTA without external support
/ 08 — FAQ
Questions teams ask before starting.
How long does a PowerMTA to KumoMTA migration take?
Eight weeks is the practical floor for a production deployment with established sender reputation that should not be disturbed. Two weeks of planning and provisioning, one to two weeks of configuration translation, three to four weeks of dual-send validation during which traffic ramps gradually to KumoMTA, then one to two weeks of cutover and PowerMTA decommissioning. Greenfield deployments with no existing reputation can complete in much less time. Migrations under heavy operational pressure, with complex multi-tenant configurations, or with hundreds of monitored domains can extend to twelve to sixteen weeks.
Do I need to re-warm my dedicated IPs after migrating to KumoMTA?
No, and this is one of the most reassuring facts about MTA migrations in general. Sender reputation lives on the IP address and the domain, not on the software that drove the SMTP transaction. When PowerMTA hands off the same IP to KumoMTA, the receiver-side reputation continues without interruption. The exception is if you are also changing IPs as part of the migration, in which case the new IPs need standard warming regardless of which MTA you came from.
Is there an automated tool to convert a PowerMTA config to KumoMTA?
No. KumoMTA's configuration model is fundamentally different from PowerMTA's directive stanzas. Translation is conceptual rather than syntactic. VMTAs map to Egress Sources, domain rules map to shaping TOML entries, DKIM stanzas map to the DKIM helper config, macros and MX rollups generally disappear because KumoMTA handles MX rollup natively. The KumoMTA team publishes a migration guide that covers the mappings, and the conversion remains a manual exercise that a deliverability engineer should perform deliberately, not a script.
Should I migrate everything at once or stream by stream?
Stream by stream during the dual-send window, then all-at-once at cutover. The dual-send strategy lets you move ten percent of Gmail traffic, then fifty, then one hundred, while keeping Yahoo, Microsoft, and Apple on the legacy path. Once each receiver has been validated on its own schedule, the final cutover is a flip rather than a leap. The all-at-once approach without dual-send is technically possible and faster, but it removes the safety net that makes the migration defensible to an executive who reads the bounce rate dashboard.
What does a rollback look like if something goes wrong?
During the dual-send phase rollback is instantaneous because PowerMTA is still operating; you simply route all traffic back through it. After cutover but before PowerMTA decommissioning rollback still works but requires reverting any IP pool changes, DKIM key rotations, or DNS adjustments made during the migration. After PowerMTA is fully decommissioned, rollback means reinstalling it under license and re-introducing the configuration you had archived, which is feasible but takes days rather than minutes. The lesson is to keep PowerMTA available for at least two weeks after cutover.
Will the migration affect my open rates, click rates, or other engagement metrics?
Not directly. Engagement metrics are receiver-side signals influenced by recipient behavior, not by the MTA driving the SMTP transaction. The only indirect path through which the MTA can affect engagement is if a placement change moves a message from inbox to spam or vice versa, which is captured in receiver-side dashboards before it shows up as an engagement delta. If your dual-send validation shows stable placement and bounce rates, your engagement metrics should remain stable through the cutover.
/ Next step
Considering the migration? We have done this for clients who needed it done right.
Email Delivery Platform operates KumoMTA as the primary engine on the managed tier and has migrated multiple production deployments off PowerMTA without disturbing sender reputation. The discovery call begins with a candid assessment of whether migration is the right call for your situation — including "stay on PowerMTA" when that fits best.