Traffic Shaping

By default, the KumoMTA server will deliver messages as quickly as possible to each destination, with few restrictions regarding number of connections, number of messages per connection, or number of messages per second. Because unthrottled sending is unwelcome by most MailBox Providers (MBPs) it is highly recommended that KumoMTA users implement traffic shaping in order to limit sending speeds to something more aligned with the expectations of the individual MBPs.

Common throttles include concurrent connection limits, messages per connection, rate of opening connections, and rate of sending messages. In addition, users can set options for various timeouts, queue sizes, and what encryption rules to use when communicating with remote hosts.

Configuring An Egress Path

All messages are relayed to external hosts along an egress path, which is defined as a combination of a routing domain, egress source, and a site name, triggered via the get_egress_path_config event.

In response to the get_egress_path_config event, the user calls kumo.make_egress_path and provided the desired parameters for the specific combination of source and destination:

kumo.on('get_egress_path_config', function(domain, source_name, site_name)
  return kumo.make_egress_path {
    max_connection_rate = '100/min',
  }
end)

The full list of parameters that can be configured for a given egress path can be found in the make_egress_path page of the Reference Manual.

The shaping.lua Helper

While users are free to implement their traffic shaping rules as they see fit, the KumoMTA team has provided the shaping.lua helper as a pre-built implementation based on static configuration files in either JSON or TOML format, with support for various configuration scopes and automated rules using Traffic Shaping Automation.

The remainder of this chapter is focused on the use of the shaping.lua helper.

Traffic Shaping Automation

Many of the largest MailBox Providers (MBPs) operate platforms that provide feedback to senders through their response codes during the SMTP conversation. This feedback will include information related to the traffic shaping patterns in use by the sending including bounces for too many connections, too many messages per connection, sending rate, and sender reputation.

To ensure optimum throughput and deliverability, KumoMTA features Traffic Shaping Automation (TSA) that monitors responses from remote hosts and adjusts traffic shaping rules on a granular level in realtime.

In This Chapter

• Scoping Traffic Shaping Rules — How KumoMTA uses domain, egress source, and site name to scope traffic shaping rules.
• MX Rollups and Provider Blocks — How domain entries map to site names, and using provider blocks for pattern-based MX matching.
• Traffic Shaping Configuration Files — Configuring shaping rules using the shaping.lua helper and TOML/JSON configuration files.
• Shaping Option Resolution Order and Precedence — How shaping options are merged and resolved across multiple configuration layers.
• Writing Custom Shaping Files — Creating your own traffic shaping rules to supplement or replace the defaults.
• Traffic Shaping Automation — Deploying the TSA daemon for automated, real-time traffic shaping adjustments.
• Testing Your Shaping Files — Validating shaping file syntax using the built-in validate-shaping tool.