Skip to content

kumo.make_egress_pool { PARAMS }

Defines an egress pool, which is a collection of weighted egress sources associated with the source of outbound traffic from the MTA.

This function is intended to be used inside your get_egress_pool event handler.

PARAMS is a lua table which may have the following keys:


Required string.

The name of the pool. This name can be referenced via make_queue_config().egress_pool.


Required list of entries.

Each entry has a name, which must refer to a source that will be resolved via your get_egress_source event, and an optional weight:

local SOURCE_TO_IP = {
  ['ip-1'] = '',
  ['ip-2'] = '',
  ['ip-3'] = '',

function setup_pools()
  return {
    ['BestReputation'] = kumo.make_egress_pool {
      name = 'BestReputation',
      entries = {
        { name = 'ip-1' },

    ['MediumReputation'] = kumo.make_egress_pool {
      name = 'MediumReputation',
      entries = {
        { name = 'ip-2', weight = 2 },
        -- we're warming up ip-3, so use it less frequently than ip-2
        { name = 'ip-3', weight = 1 },

local POOLS = setup_pools()

kumo.on('get_egress_source', function(source_name)
  return kumo.make_egress_source {
    name = source_name,
    source_address = SOURCE_TO_IP[source_name],

kumo.on('get_egress_pool', function(pool_name)
  return POOLS[pool_name]

The weight is used as part of Weighted Round-Robin selection for the source from the pool.

If the weights are all equal, or are all left unspecified, then simple round-robin selection of sources will occur.

Otherwise, the weight influences how often a given source will be used for traffic originating from this pool.

A weight of 0 is permitted: it is equivalent to not including the associated sources in the list of entries.

If weight is left unspecified, it defaults to 1.


Optional time-to-live specifying how long the pool definition should be cached. The cache has two purposes:

  • To limit the number of configurations kept in memory at any one time
  • To enable data to be refreshed from external storage, such as a json data file, or a database

The default TTL is 60 seconds, but you can specify any duration using a string like "5 mins" to specify 5 minutes.

Last update: 2023-08-08
Created: 2023-05-30