GreenArrow Email Software Documentation

Bounce Processor Configuration

Overview

This page describes the bounce processor’s configuration files. See the Bounce Processor Concepts page for an overview of how GreenArrow’s bounce processor works, and definitions of some of the terms used on this page.

Main Configuration file

Most of the bounce processor’s configuration is contained within the following file:

/var/hvmail/control/bounce_processor.conf

To validate the syntax of this file, run:

/var/hvmail/bin/hvmail_bounce_processor --check-config

Updates to this file are automatically re-read by the bounce processor within one minute.

If there are errors in this file, bounces will not be processed and the errors will be logged to /var/hvmail/log/bounce-processor/current. Bounces will accumulate and potentially slow GreenArrow down until the error is corrected.

File Format

This file is a JSON document where the root is an object. The following keys may be defined:

default

object

/

optional

A Bounce-Configuration-Object that defines the default configuration.

studio

object

/

optional

A Bounce-Configuration-Object that defines the default configuration for GreenArrow Studio.

studio_by_mailing_list_id

object

/

optional

Defines configurations for individual GreenArrow Studio mailing lists. It is an object where each key is a mailing_list_id and each value is a Bounce-Configuration-Object.

by_listid_prefix

object

/

optional

Defines configurations by ListID prefix. It is an object where each key is a ListID prefix and each value is a Bounce-Configuration-Object.

A ListID Prefix is a string of contiguous lowercase letters OR numbers at the beginning of the ListID. For example, the prefix of “foo100” is “foo”, the prefix of “bar99baz” is “bar”, the prefix of “99qux” is “99”, and the ListID “_foo” has no prefix.

by_listid

object

/

optional

Defines configurations for specific ListIDs. It is an object where each key is a ListID and each value is a Bounce-Configuration-Object.

Bounce-Configuration-Object

Each Bounce-Configuration-Object can have the following optional keys:

hard_req_count

integer

Number of hard bounces that must happen sequentially before an address will be marked as bad.

hard_req_days

integer

Minimum number of days between first and last hard bounces, in order for an address to be marked as bad.

hard_allow_missing

integer

Number of emails that may be sent without receiving a hard or soft bounce, without interrupting a sequence of hard bounces.

soft_req_count

integer

Same as hard_req_count except for soft bounces.

soft_req_days

integer

Same as hard_req_days except for soft bounces.

soft_allow_missing

integer

Number of emails that may be sent without receiving a soft or hard bounce, without interrupting a sequence of soft bounces.

store_bounce_details_length

integer

The number of characters of bounce text to store. Set to zero to not store bounce text.

bounce_codes

object

Mapping of integer bounce codes to the string “hard”, “soft”, or “other” to define the type of bounce. Any bounce codes not defined as “hard” or “soft” are categorized as “other”. See the Bounce Processor Concepts page for a list of integer bounce codes and the definitions of hard, soft and other bounces.

Default Settings

GreenArrow’s default settings are as follows.

Setting Default Value
hard_req_count 1
hard_req_days 0
hard_allow_missing 0
soft_req_count 2
soft_req_days 10
soft_allow_missing 0
store_bounce_details_length 1024

Default bounce code mappings:

Bounce Code Bounce Type
10 hard
20 soft
21 soft
22 soft
23 other
29 soft
90 hard

Configuration Precedence

The bounce processor goes through the following list when processing GreenArrow Studio bounces. The first matching entry is used:

  1. The id of the Mailing List is searched for in studio_by_mailing_list_id
  2. The configuration defined in the studio object, if present
  3. The configuration defined in the default object, if present
  4. GreenArrow’s default settings

The bounce processor goes through the following list when processing bounces from non-GreenArrow Studio sources. The first matching entry is used:

  1. The ListID is searched for in by_listid
  2. If the ListID has a prefix, a configuration in by_listid_prefix is searched for
  3. The configuration defined in the default object, if present
  4. GreenArrow’s default settings

Example Configuration

{
   "default" : {
      "hard_allow_missing" : 1,
      "hard_req_count" : 2,
      "hard_req_days" : 0
   },
   "by_listid" : {
      "bb" : {
         "soft_req_count" : 2,
         "soft_req_days" : 2,
         "soft_allow_missing" : 1
      }
   },
   "studio_by_mailing_list_id" : {
      "66" : {
         "hard_req_count" : 1,
         "hard_req_days" : 0,
         "hard_allow_missing" : 0,
         "bounce_codes" : {
            "10" : "hard",
            "20" : "soft",
            "21" : "soft",
            "22" : "soft",
            "23" : "other",
            "29" : "soft",
            "90" : "hard"
          }
      }
   }
}

Default Configuration

The configuration file is blank by the default. This implies the following settings:

{
   "default" : {
      "hard_req_count" : 1,
      "hard_req_days" : 0,
      "hard_allow_missing" : 0,
      "soft_req_count" : 2,
      "soft_req_days" : 10,
      "soft_allow_missing" : 0,
      "store_bounce_details_length" : 1024,
      "bounce_codes" : {
         "10" : "hard",
         "20" : "soft",
         "21" : "soft",
         "22" : "soft",
         "23" : "other",
         "29" : "soft",
         "90" : "hard"
      }
   }
}

bounce.concurrency

This file controls the number of concurrent processes to use for bounce processing. Valid values are 1-100.

Concurrent bounce processing was introduced in GreenArrow Engine 4.1.153-0, which was released in January 2017. This means that until this release, this setting’s effective value was 1, which was sufficient in the vast majority of installations. Having a single bounce processing process only represented a bottleneck on some installations which had exceptionally high bounce rates.

The default value is 2. To restore the default, run:

echo 2 > /var/hvmail/control/bounce.concurrency

bounce.max_gap_days

If no emails are sent to an email/ListID combination in this many days, then the repeat bounce processing system will forget about repeat bounces for this email/ListID combination. This means that you can’t have a gap in sending more than this many days.

The default value 75. To restore the default, run:

echo 75 > /var/hvmail/control/bounce.max_gap_days

bounce.queue_size.soft and bounce.queue_size.hard

These files are used to apply back pressure to the rest of the MTA if more than the configured number of bounces or FBL messages accumulate in the bounce processor’s queue. This back pressure slows down the MTA and can impact both GreenArrow’s delivery and message acceptance performance.

Back pressure is applied in the form of a queuing delay. This is done to prevent larger issues, like memory exhaustion or never catching up on bounce processing from occurring.

The soft limit is reached when the number of messages in the bounce processor’s queue exceeds the value set in the /var/hvmail/control/bounce.queue_size.soft configuration file. When this happens, a small amount of latency is added to the process of queuing new bounces.

The hard limit is reached when the number of messages in the bounce processor’s queue exceeds the value set in the /var/hvmail/control/bounce.queue_size.hard configuration file. When this happens, the queuing of new bounces is delayed until after the number of messages in the bounce processor’s queue falls below the hard limit.

The default soft limit is 3000 and the default hard limit is 5000. Commas should not be used in these values. To restore the defaults, run:

echo 3000 > /var/hvmail/control/bounce.queue_size.soft
echo 5000 > /var/hvmail/control/bounce.queue_size.hard

bounce.queue_type

This file controls the type of bounce processor queue that’s used. Valid values are redis and maildir.

This file only controls the handling of bounce messages. Spam complaints always get delivered to a maildir.

redis is recommended in most situations because it offers better performance by storing bounces in a RAM-based Redis queue instead of a disk-based maildir.

The default value is redis. To restore the default, run:

echo redis > /var/hvmail/control/bounce.queue_type

After changing this value, you’ll need to restart the bounce processor to apply changes. To restart the bounce processor, run:

svc -tu /service/hvmail-bounce-processor

After restarting the bounce processor, verify that it stays up:

hvmail_init status | grep hvmail-bounce-processor

opt.treat_qsbf_bounces_as_local_server_names and opt.treat_all_qsbf_bounces_as_local

GreenArrow has internal bounce codes for messages that aren’t delivered because they were either dumped from the queue or their queue lifetime expired while delivery was paused. These internal bounce codes normally only occur locally, so GreenArrow’s default configuration only assigns special meanings to these internal bounce codes when the bounces are synchronous.

If you have multiple GreenArrow servers and they relay mail to each other, then you may want to overwrite this default behavior, and allow the internal GreenArrow bounce codes to be processed for asynchronous bounces. This is where the opt.treat_qsbf_bounces_as_local_server_names and opt.treat_all_qsbf_bounces_as_local files come in. Neither of these files exist by default.

To configure GreenArrow to process these internal bounce codes if they originate from specific server(s), add each their Server Names, one per line to /var/hvmail/control/opt.treat_qsbf_bounces_as_local_server_names.

echo mailer.example.com >> /var/hvmail/control/opt.treat_qsbf_bounces_as_local_server_names

To configure GreenArrow to process these internal bounce codes regardless of where they originate, set /var/hvmail/control/opt.treat_all_qsbf_bounces_as_local to a TRUE value, such as 1:

echo 1 > /var/hvmail/control/opt.treat_all_qsbf_bounces_as_local

Updates to the above files are automatically read by the bounce processor without any service restarts.


Copyright © 2012–2024 GreenArrow Email