If you are managing multiple mailing lists, and would like to process them together -- that is, on a single MailBounce run -- then you will need to set up the multiple mailing list "Configuration" file. This documentation file tells you how to format the Configuration file, and discusses the issues associated with multiple-list processing.

Multi-List Processing:

Using the "Configuration" file, multiple mailing lists -- up to the limit of your MailBounce license -- can be processed on a single MailBounce run. (Thus, if you have purchased a three-list license, you may process up to three lists on a single pass; if you have purchased an unlimited-list license, then the number of lists you may process on a single pass is unlimited.)

Note, however, that the bounce files are still processed as a single batch of files, and the address-matching phase is similarly executed in batch mode. In other words, if you have three different lists, with separate bounce files and subscriber lists, MailBounce will first process all three bounce files, then it will check all of the bounced addresses against the bounce-tracking files and the thresholds that you have selected, and then it will check all of the expired addresses against all three of your subscriber lists.

If you prefer to process each list completely separately from the others, then you should run separate instances of MailBounce, with different Preferences files (configured for each list). The Multi-List feature is designed for cases in which it is preferable to lump everything together into a single pass.

Activating The Feature:

The Multi-List Configuration file is separate from the Preferences file. However, MailBounce will need to know the name of your Configuration file in order to find it; you accomplish this by entering the name of the Configuration file into your Preferences file. For example, if your Configuration file is named "MailBounce_Configuration_File.txt", then you will make the following entry in your Preferences file:

    multi-list configuration file name = 'MailBounce_Configuration_File.txt'

The Configuration file can be used to process multiple bounce files, or multiple subscriber lists ("address lists"), or both. You must be sure to select the correct "use configuration file" switch within the Preferences file. The two basic settings are:

    process multiple bounce files = 'YES'
    process multiple subscriber lists = 'YES'

Of course, if you are using the multi-list config file to process bounces, but not to maintain multiple subscriber lists, then you should use the following settings:

    process multiple bounce files = 'YES'
    process multiple subscriber lists = 'NO'

Similarly, if you are using the multi-list config file to process multiple mailing lists, but the bounces from all of those mailing lists are feeding into a single bounce file, the you would use these settings ...

    process multiple bounce files = 'NO'
    process multiple subscriber lists = 'YES'

If both cases apply -- that is, you have some mailing lists with separate bounce files and some with combined bounce files, then you should set both options ...

    process multiple bounce files = 'YES'
    process multiple subscriber lists = 'YES'

... and individually select which segments within the multi-list configuration file should be used for bounce processing and which should be used for address matching (or both). This is accomplished within the multi-list configuration file; we'll discuss this in more detail below.

Configuration File Format:

The Configuration file has a format that is very similar to the Preferences file. The first record is an identifier that allows MailBounce to recognize the file type and version number:

list configuration file version = '1.0'

Next, you must specify a configuration for each list that you are planning to process. It is important to note that activating Multi-List Processing causes the Preferences settings that you specified in your Preferences file to be used strictly as a "template" for the Configuration file. That is, whenever MailBounce encounters a new configuration while processing the configuration file, it first resets all of the Preferences items to their original settings, as specified in the Preferences file, and then reads in the new configuration and "overlays" the new configuration's settings on top of the Preferences settings. Thus, it is not necessary to repeat the entire Preferences file for each configuration (though you certainly may if you want to); you must specify only the settings that are actually DIFFERENT from those in your Preferences file. This allows new configurations to be added to the Configuration file very easily.

Each configuration's settings must be placed within "START CONFIGURATION" and "END CONFIGURATION" commands; for example:

    START CONFIGURATION
        <configuration #1>
    END CONFIGURATION

    ; Next configuration ...

    START CONFIGURATION
        <configuration #2>
    END CONFIGURATION

The "START CONFIGURATION" and/or "END CONFIGURATION" commands may be shortened to just "START CONFIG" and "END CONFIG" if you prefer.

Each block that appears between a START CONFIG and an END CONFIG command is referred to as a "configuration segment" (or shortened to just "configuration" or "segment"). Each configuration segment contains the settings that MailBounce needs to properly process that segment. Typically, each mailing list will have its own configuration segment in the Multi-List Configuration File.

The items shown above as <configuration #n> are any series of Preferences-style entries. So, for example, you could simply specify a new subscriber list to be processed:

    START CONFIGURATION
    subscriber list file name = 'my_subscriber_list.txt'
    END CONFIGURATION

Or, if you run a site with several different "dog owner" lists, for example, your config file might have entries like this:

    START CONFIGURATION
    subscriber list file name = 'doberman_list.txt'
    END CONFIGURATION

    START CONFIGURATION
    subscriber list file name = 'german_shepherd_list.txt'
    END CONFIGURATION

    START CONFIGURATION
    subscriber list file name = 'golden_retriever_list.txt'
    END CONFIGURATION

In this example, however, MailBounce will write all of the server commands to the default server file -- that is, the one provided in the Preferences file -- since no explicit server files were specified in any of the configuration segments. If you want to specify a different server file for each list, you could do something like this:

    ; Doberman list

    START CONFIGURATION
    subscriber list file name = 'doberman_list.txt'
    server file name = 'doberman_server_file.txt'
    END CONFIGURATION

    ; German Shepherd list

    START CONFIGURATION
    subscriber list file name = 'german_shepherd_list.txt'
    server file name = 'german_shepherd_server_file.txt'
    END CONFIGURATION

    ; Golden Retriever list

    START CONFIGURATION
    subscriber list file name = 'golden_retriever_list.txt'
    server file name = 'golden_retriever_server_file.txt'
    END CONFIGURATION

Similarly, each list might have its own bounce file:

    ; Doberman list

    START CONFIGURATION
    bounce file name = 'dobie_bounces.txt'
    subscriber list file name = 'doberman_list.txt'
    server file name = 'doberman_server_file.txt'
    END CONFIGURATION

    ; German Shepherd list

    START CONFIGURATION
    bounce file name = 'shepherd_bounces.txt'
    subscriber list file name = 'german_shepherd_list.txt'
    server file name = 'german_shepherd_server_file.txt'
    END CONFIGURATION

    ; Golden Retriever list

    START CONFIGURATION
    bounce file name = 'retriever_bounces.txt'
    subscriber list file name = 'golden_retriever_list.txt'
    server file name = 'golden_retriever_server_file.txt'
    END CONFIGURATION

In these cases, all three bounce files will be processed in sequence; if bounces are being tracked, then all bounced addresses will be compared against the tracking data and thresholds; and finally, all defunct addresses will be compared against all three subscriber lists (in the order shown).

It is important to note that, when processing a Multi-List Configuration file, the default settings in the Preferences file are not processed automatically; this allows you to specify the most commonly-used parameters, even if they won't actually be used together in a single configuration pass. So, if you want to process the exact configuration in your preferences file, you must enter a START CONFIGURATION and END CONFIGURATION command pair, with no intervening lines; for example:

    START CONFIGURATION
    END CONFIGURATION

Thus, in our example above, let's suppose that we enter the information for the Doberman list into the Preferences file as the default configuration -- i.e., in the Preferences file, we enter the Doberman list's file names for "bounce file name", "subscriber list file name", and "server file name". We could then modify the Configuration example as follows:

; Doberman list (this tells MB to run the default configuration)

START CONFIGURATION END CONFIGURATION

; German Shepherd list

START CONFIGURATION bounce file name = 'shepherd_bounces.txt' subscriber list file name = 'german_shepherd_list.txt' server file name = 'german_shepherd_server_file.txt' END CONFIGURATION

; Golden Retriever list

START CONFIGURATION bounce file name = 'retriever_bounces.txt' subscriber list file name = 'golden_retriever_list.txt' server file name = 'golden_retriever_server_file.txt' END CONFIGURATION

There would not be anything wrong with reiterating the Doberman list's "bounce file name", "subscriber list file name" and "server file name" entries in the configuration file (as in the previous example), and it might even make the file easier to understand and debug. This example was primarily for the purpose of illustrating that the default Preferences configuration will not be processed unless MailBounce is explicitly instructed to do so -- as shown in the Doberman list's example, above.

An important point is that the default Preferences file configuration is reloaded every time MailBounce encounters a new configuration; thus, settings are not "sticky" from one configuration to the next. Once an "END CONFIG" command is encountered, MailBounce resets all of the original preferences parameters prior to processing the next list's configuration. Thus, if you have a specific configuration item that you find yourself repeating from configuration to configuration, it would probably be best to simply insert it into the Preferences file rather than repeat it throughout the Configuration file. Even if you need to change it once or twice in the Configuration file, the default value will be restored for each new configuration, which could save you quite a bit of typing.

Note that some people prefer to explicitly spell out ALL of the configuration items for each list, regardless of whether they are defaulted in the Preferences file, so that all settings are shown in the file; this is perfectly acceptable, though it's a bit more typing.

Controlling Execution Within Configuration Segments

Depending on your site's configuration, you might have some segments within the Config file that are used only for bounce files and some that are used only for subscriber lists (i.e., address matching). You can disable bounce-file processing and/or address matching within any configuration segment via the following commands:

    process bounces in this configuration = 'NO'
    match addresses in this configuration = 'NO'

These settings instruct MailBounce to skip the specific configuration segment in which the command(s) appear; MailBounce will then move on to the next segment. The segment will be skipped only for the mode that is specified (i.e., either "process bounces" or "match addresses"). For example, if the following command is encountered within a particular configuration segment:

    process bounces in this configuration = 'NO'

... MailBounce will not use that configuration for bounce processing, but will still use it for address matching (unless "match addresses in this configuration" is also present and set to 'NO'; note that this will effectively disable the segment entirely).

Similarly, if a specific configuration should not be used for address matching, then it should include the following command:

    match addresses in this configuration = 'NO'

The commands may appear anywhere in the segment -- that is, as long as they appear somewhere between the START CONFIG and END CONFIG commands, then processing for that specific block will be disabled. You can optionally include the settings in EVERY segment, with each one set to either 'YES' or 'NO', depending on whether you want processing enabled or disabled for that bnlock. However, the default case for each command -- i.e., when the command(s) are not present in any given segment -- is 'YES'. Thus, you actually need to include the commands only if you are disabling processing for that segment.

Controlling the Days During Which a Segment May Execute:

In some cases, it may be desirable to have a particular configuration segment execute on specific days (or not execute on specific days); the following settings will allow you to control the days on which a particular segment will execute:

    process this configuration every = '3 DAYS'
    offset processing by = '1 DAY'

Alternatively, you may select specific days of the week for processing:

    process this configuration every = 'FRI, SAT, SUN'

These settings allow you to specify that the configuration segment in which they appear is to be processed only on the days stated; thus, the configuration segment is skipped entirely on the intervening days, regardless of any other settings that may be present in that segment.

If the setting is for a certain number of DAYS or WEEKS, MailBounce will determine the start date internally; thus, the "offset" setting is intended to allow you to 'adjust' the actual processing date one way or another. Positive offsets move the effective date back in time, and negative settings move it forward in time. For example, if you specify:

    process this configuration every = '1 WEEK'
    offset processing by = '0 DAYS'

... and you find that the segment is executing on Fridays, but you want it to execute on Mondays, then you could use the offset setting to either move the processing day back by three days ...

    process this configuration every = '1 WEEK'
    offset processing by = '3 DAYS'

... or move it forward by four days:

    process this configuration every = '1 WEEK'
    offset processing by = '-4 DAYS'

Both options will have the same net effect.

Note that the settings in each case may be expressed in DAYS, WEEKS, or as specifc days of the week. Thus, some valid examples are:

    process this configuration every = '2 WEEKS'
    offset processing by = '3 DAYS'

    process this configuration every = '2 WEEKS'
    offset processing by = '-1 WEEK'

    process this configuration every = 'MONDAY and FRIDAY'

If you specify the setting using days of the week (like the last entry above), then any single day or combination of days can be used; days can be spelled out or shortened, but must contain at least the first three letters. Day names may be in upper case, lower case, or mixed case. Days may be separated by spaces, commas, spaces and commas, the words "and" or "or", etc. Days may appear in any order. Thus, all of the following are valid settings:

    process this configuration every = 'Monday Saturday'
    process this configuration every = 'FRIDAY, Saturday, and sunday'
    process this configuration every = 'wed, Saturday, or TUESDAY'
    process this configuration every = 'Thursday'

If you specify the setting using days of the week, then there is no need to use the "offset" setting, so MailBounce will ignore any offset setting in that configuration.

Note that these commands are effective only within the enclosing START CONFIG and END CONFIG block in which they appear. Also, you do not need to include these commands in any configuration segment; leaving them out entirely will cause the segment to execute on every run.

Valid Configuration Settings

Though any of the Preferences-file settings may be specified in the Configuration file, note that only those that apply to either bounce processing or address matching will actually have any effect on the configuration. In other words, specifying a different soft-bounce tracking file will be totally useless in the Configuration file, since only a single soft-bounce tracking file is used by MailBounce -- even for multi-list configurations. (If you really do need to specify different tracking files or bounce thresholds, etc., then you really should be processing the lists separately, using different instances of MailBounce and different Preferences files.)

The valid configuration-file settings for bounce processing and address matching are shown below. Also, be aware that some of the settings are "active" in both sections, and some are unique to only one section; all settings are shown wherever they are active:

Bounce Processing

allow e-mail address with unsub bounce file name bounce file format detailed display diagnostics file display unprocessed bounces enable hard bounce tracking enable soft bounce tracking error log file list server type mail block file name process redirects process soft bounces process unsub requests scratch file name screen display summary file track sites that are blocking mail from this list unrecognized bounces file name use ignored file write unrecognized bounces to file

execution control within the config file: process this configuration every offset processing by process bounces in this configuration

Address Matching

address removal mode BCC file name BCC file BCC fuzzy file name BCC redirects file name BCC redirects fuzzy file name separate server file for redirects separate BCC file for redirects detailed display diagnostics file error log file extended unsubscribe checking formatted server file formatted subscriber list fuzzy matching sensitivity global remove file name list name list password list server type process redirects process unsub requests reject unmatched addresses screen display secondary list name secondary list password redirects file name redirects fuzzy file name separate files for redirects separate fuzzy files server file name server fuzzy file name subscriber list backup file name subscriber list file name subscriber list file format summary file update subscriber list directly use ignored file use global remove file match bounce addresses to subscriber list

execution control within the config file: process this configuration every offset processing by match addresses in this configuration

Delimiters:

As discussed above, each configuration segment must start with

    START CONFIGURATION
     -- or --
    BEGIN CONFIGURATION

(your choice; I use "START", but they are equivalent).

Each configuration segment must end with:

    END CONFIGURATION

In each case, the word "CONFIGURATION" may be shortened to "CONFIG". They are not case sensitive; I show them in all caps simply to make it easier to read the configuration segments. Also, do not put valid Preferences items between configurations (i.e., after an END CONFIG and before a START CONFIG); MailBounce will process them! If you want to "store" configuration items in the file, comment them out.

Other Valid Settings:

Since any and all valid prefs items are processed in each configuration, the following settings are also permissible in the Configuration file, though they really have no utility there. Note that changes to these items are "sticky" -- that is, they will not be reset to their defaults at the start of each new configuration segment:

    quit when finished
    name
    organization
    processor
    registration type
    registration number

Important Note: If you specify invalid registration information, MailBounce will skip over that configuration, and all subsequent configurations, until valid data is re-entered.

General Syntax

The syntax rules are the same as in the Prefs file (for probably obvious reasons): The first record must be the file version number, the last processable item in the file must be an "END CONFIGURATION", and the items between each START CONFIG and END CONFIG pair may appear in any order. Comment lines are those whose first non-blank character is a semicolon ";".

WARNINGS ...

There Are Some Complex Issues Associated With Using The Multi-List Configuration Feature!

To avoid problems, follow these guidelines when constructing your configuration file:

Unless you are using incremental bounce processing (refer to the Bounce_Tracking file), you should limit our Multi-List Configuration File to only those lists that have similar posting rates. This is very important, or else you will "lose sync" on your tracked bounces. Refer to the bounce tracking documentation for information on incremental bounce processing if you plan to group lists with different posting rates.
If you plan on having MailBounce write to the default primary output files (i.e., the server, BCC, server fuzzy, and BCC fuzzy, redirects, and fuzzy redirects files, as specified in the Preferencess file), then those configurations should appear FIRST in the Configuration file. Once those files (and only those files) are opened, they are allowed to remain open through consecutive configurations UNTIL any of them is explicitly changed in a configuration segment; at that time, the changed file(s) will be closed, and the new file(s) will be opened. From that point on, it is CRITICAL that you specify a new output filename in EVERY new configuration segment for each of the files that has already been closed, as failing to do so will cause the default file(s) (as specified in the Preferences file) to be re-opened -- and thus overwritten.

To illustrate this last point (since it is a little complex), let's revisit our "dog" lists. Suppose that we have made the following entries in the Preferences file (the first two entries merely instruct MailBounce to open and process the Configuration file):

    multi-list configuration file name = 'config.txt'
    use configuration file = 'YES'

    subscriber list file name = 'doberman_list.txt'

    server file name = 'mailbounce_server_file.txt'
    redirects file name = 'redirected_addresses.txt'
    BCC file name = 'mailbounce_bcc_file.txt'

    server fuzzy file name = 'mailbounce_server_fuzzy_file.txt'
    redirects fuzzy file name = 'redirected_fuzzy_addresses.txt'
    BCC fuzzy file name = 'mailbounce_bcc_fuzzy_file.txt'

These are now our defaults (among other settings, which we won't worry about for this example). Now, suppose that I want to use the same server and BCC files for the Doberman list and the German Shepherd list, but I want to use different server files for the Golden Retriever list and the Poodle list. Since the files shown above will be opened at the start of Configuration-file processing, and will be left open until different file names are specified, we can set up the Configuration file -- named, in this case, "config.txt" -- as follows (note that the first case simply instructs MailBounce to process the default configuration):

    ; Doberman list

    START CONFIGURATION
    END CONFIGURATION

    ; German Shepherd list

    START CONFIGURATION
    subscriber list file name = 'german_shepherd_list.txt'
    END CONFIGURATION

    ; Golden Retriever list

    START CONFIGURATION
    subscriber list file name = 'golden_retriever_list.txt'
    server file name = 'golden_retriever_server_file.txt'
    server fuzzy file name = 'golden_retriever_server_fuzzy_file.txt'
    END CONFIGURATION

    ; Poodle list

    START CONFIGURATION
    subscriber list file name = 'poodle_list.txt'
    server file name = 'poodle_server_file.txt'
    server fuzzy file name = 'poodle_server_fuzzy_file.txt'
    END CONFIGURATION

Notes Regarding This Example:

It is now very important that both the "server file name" and "server fuzzy file name" parameters be specified in EVERY configuration segment that follows. To fail to do so will cause MailBounce to re-open and rewrite the server and server-fuzzy files specified in the Preferences file.
Note that the "BCC" files and "secondary server" files, as specified in the Preferences file, are still open and still being written to without problem. Since their file names have not been changed (so far) in the Configuration file, they will remain open and will continue to be appended to without error. Once any of those file names is changed in the Configuration file, all subsequent configuration segments must identify unique file names for those entries.
Thus, you can generate unique server files for each list that you process, but lump all of the defunct addresses into the same BCC file (for example), so that you need to send out only one "alert" message to all of the subscribers that have been removed from the lists.

We have included a sample Multi-List Configuration File to give you a starting point for setting up your own. If you have any questions regarding the Configuration file or configuration options, feel free to contact us at Smart Mail Solutions, Inc.

[home]

[ReadMe]

Processing Multiple Mailing Listswith MailBounce

Current Release: v6.0, May 2003