This is a detailed functional description of MailBounce. Refer to the MailBounce Quick Tour for a quick introduction to MailBounce. This tutorial goes into significantly more detail on how to configure MailBounce and how the program operates; it will walk you through the basic steps for setting up and running MailBounce, interpreting the output, and getting the most out of the application.

Brief Revision History

Early 1996: Initially implemented the "Bounce Processor" in a shell scripting language (version 1). Was painfully slow, but proved out the basic concept.

Fall 1996: Ported the shell script to Fortran (version 2), named the program "SmartBounce," added several new features and improved functionality (version 3).

Winter/Spring 1997: Ported the Fortran version to ANSI C for Macintosh, Windows, and various Unix platforms (version 4). First public release of the program.

Fall 1997: Released the first major public upgrade to SmartBounce (version 5).

Winter 2000: Sold the code base to Return Path, Inc., in New York City. Smart Mail Solutions retained the rights to continue to upgrade and market the application.

Winter 2003: Application renamed "MailBounce" to avoid confusion with Return Path's hosted product. Next major revision released (version 6).

Bounce Processing: Preparation

Before running MailBounce, you must configure your Preferences file. There are many preferences settings and options; please refer to the Preferences file documentation for explanations of those options, plus tips on selecting various settings.

Next, collect all your bounces into a single file. (You can optionally have MailBounce process multiple bounce files.) You do not always need to extract your bounces from your mail client; for example, Eudora mailboxes may be processed directly. (In fact, processing the mailboxes directly is recommended. Just tell MailBounce where the mailbox is located; MailBounce will simply read the bounces straight from the mailbox.)

If you plan to have MailBounce check addresses against your subscriber list, then you will have to tell MailBounce where that file is located. If you are using Eudora, you can process the subscriber list directly from your mailer client's mailbox.

Then simply launch the program.

Bounce-File Processing

MailBounce reads in the bounce file, processes each bounce that it recognizes, extracts the user address from the bounce message, and classifies the bounce as either a "hard" bounce, a "soft" bounce, a "redirect," or an "unsubscribe." To define those terms:

Hard Bounce: "550 User unknown" and the like; basically, anything in which you can conclude that you will never deliver mail to that address.
Soft Bounce: Fatal timeouts, mailbox full, DNS errors, etc.; essentially, everything that is not classified as a "hard bounce."
Redirect: An automated notification of a new address for the subscriber. MailBounce will optionally remove the old address and subscribe the new one for you.
Unsubscribe: MailBounce will optionally recognize and process unsubscribes for you. If you are using a Majordomo list server, it will also process Majordomo administrative requests for you when you activate the unsubscribes feature.

Once the bounce file has finished processing, MailBounce will have a list of bounced addresses, each categorized as "hard," "soft," "redirect," or "unsubscribe." The next step is to see how many times each of the hard- or soft-bouncing addresses has bounced in the past; MailBounce accomplishes this via bounce tracking ...

Bounce Tracking

Each bounce is compared to a "bounce tracking" file that is aggregated over time as you run MailBounce. In your Preferences file, you can select separate thresholds at which you want any repeatedly bouncing addresses to be declared as "defunct"; these thresholds are referred to as your "bounce tracking thresholds." (See the Bounce_Tracking file for details on selecting bounce-tracking thresholds.) MailBounce compares each bounced address against those in the tracking file, and each address that has bounced beyond the threshold is marked as "defunct" (i.e., it is marked for deletion). Finally, your tracking file is updated with all the bounced addresses from the current bounce file.

Address Matching

In the final step, MailBounce opens your subscriber file and compares each expired address against those in your file; if an exact match is found, the address is added to the server file for removal from the mailing list. If an exact match was not found for any given address, MailBounce will optionally attempt to "fuzzy match" the address against your subscriber list; this allows it to match bounce addresses such as "jane_white@mail.company.com" to subscriber addresses like "jane_white@company.com" or even "jwhite@gateway.division.company.com".

Output Files

Every time an address match is found, it is written to a "server file" in the format used for remote maintenance of the selected mailing list; thus, you can simply send this entire file to the list server once MailBounce finishes processing. (The server file already contains your list name and password, assuming that you have filled in those fields in the Preferences file.) For example, if the address "mailuser@foo.bar" is declared defunct, and you've told MailBounce (in the Preferences file) that (1) you're using a ListProc list server, (2) your list name is "funlist" and (3) the list password is "OmiGosh", then it will write the following line to the output file:

delete funlist OmiGosh mailuser@foo.bar

If you told MailBounce that you were using Majordomo, it would write:

approve OmiGosh unsubscribe funlist mailuser@foo.bar

etc...

MailBounce recognizes virtually all of the common automated list servers currently in use. See the Preferences documentation for a complete list of all recognized list servers. Refer to the New_Server file for instructions on submitting new list server types to the developer.

Note: If you are running a manually-managed list, you can optionally have MailBounce update your subscriber list directly.

MailBounce also writes out an optional "BCC" file. This is a comma-delimited set of defunct addresses (the same set of addresses that was written to the server file) that can be used to send out a "form letter" to all the removed subscribers (via BCC, of course -- hence the name). It informs the subscribers that they have been removed from the mailing list because their mail has been bouncing. (For example, "Your address has been removed from the mailing list 'listname' because mail to your address has been bouncing....") A sample form letter is provided in the Bounce Alert file.

Also, MailBounce will optionally write separate "fuzzy" files: In case you don't quite trust the fuzzy matching algorithm, you can ask MailBounce to produce separate server and BCC files for all the fuzzy matches. This will potentially generate six output files, as follows:

Server File: A formatted list of server commands for removing all addresses that EXACTLY matched addresses in your subscriber list.
"Fuzzy" Server File: A formatted list of server commands for removing all addresses that FUZZY matched addresses in your subscriber list.
BCC File: A comma-delimited list of all addresses that EXACTLY matched addresses in your subscriber list; the addresses in this file are in a format suitable for placing on the BCC line of a message informing your subscribers that they have been removed from the mailing list. (A sample letter is included with the documentation for this purpose.)
"Fuzzy" BCC File: An unformatted list of all addresses that FUZZY matched addresses in your subscriber list; the addresses in this file are in a format suitable for placing on the BCC line of a message informing your subscribers that they have been removed from the mailing list.
Redirects File: A formatted list of SUBSCRIBE commands for all subscriptions that have been automatically changed ("redirected") to new addresses, and that have EXACTLY matched addresses in your subscriber list.
"Fuzzy" Redirects File: A formatted list of SUBSCRIBE commands for all subscriptions that have been automatically changed ("redirected") to new addresses, and that were FUZZY matched to addresses in your subscriber list.

In each case, the fuzzy matches can optionally be combined with the exact matches, to produce a smaller number of files. Similarly, the "redirects" file can be combined with the server file (for list servers that support that feature) for even fewer output files. You might want to keep them separate, though, until you are comfortable that MailBounce's fuzzy-matching algorithm is working well for you -- especially if you have selected the more advanced fuzzy-matching options. (To date, there has not yet been a single report of an incorrect fuzzy match. However, at the more permissive matching levels, it is quite possible to make an incorrect match.)

NOTE: Unless instructed to do so, MailBounce will never "remove" any addresses from your mailing list itself; MailBounce merely generates one or more files containing the defunct addresses that it finds. This list is created in the proper format for your list server; then all you need to do is mail the file to the server. You can manually add or delete any addresses you wish, prior to sending the file to the server. For addresses that bounce repeatedly, but that you do not want to remove from the subscription list (they might be bouncing in error, for example), you can enter those addresses into an "Ignored" file, which instructs MailBounce to skip over them when they are encountered in the bounce file.

Other Output Files

Diagnostics file: The diagnostics file is a detailed description of EVERY action taken by MailBounce, as well as notification of any bounces that it recognized but could not process. This file is a complete transcript of the screen display, and contains a lot of useful information. It is recommended that you look over this file after each run.

Summary file: The diagnostics file is usually pretty extensive, so there is an option to have MailBounce create a Summary file, either in place of the Diagnostics file, or in addition to it. The Summary file contains a listing of all the more significant actions that were taken by MailBounce, and will usually provide a sufficient overview of the processing run for most purposes. Since the Summary file does not contain the same level of detail as the Diagnostics file, it is recommended that you still have MailBounce create a Diagnostics file, even if you use only the Summary file; if there is ever a problem, you will probably have to send your Diagnostics file to Smart Mail Solutions, Inc., so we can diagnose the problem.

Error Log: The Error Log contains a listing of any significant warnings and/or errors encountered during processing. This includes references to unprocessed bounces, array overflows, unmatched addresses, etc.

Using the Results

Once MailBounce has finished processing, you simply mail the "Server" file off to your list server, and optionally send the form letter to all of the addresses in the "BCC" list, informing the deleted subscribers that they have been removed from the mailing list because their mail has been bouncing. (The reason for doing this is that some ISP will send errant intermittent bounces -- e.g., if a mail server or firewall has been configured incorrectly. The removal message, if received by the user, provides notification that there is a mail-delivery problem with his or her address.) A sample form letter is included in the documentation for this purpose.

For best bounce-tracking results, MailBounce should be run on a regular schedule. Refer to the Bounce Tracking file for more information on bounce tracking, including pointers on Preferences-file settings.

Getting More from MailBounce

This was intended to be an introduction to MailBounce rather than a complete description of its capabilities. The detailed documentation contains significantly more information on how to configure, run, and interpret the output from MailBounce. In particular, there are many advanced features that are not covered in this quick tour of the program.

What if MailBounce doesn't recognize one of my bounces?
If you are a registered user, then you should fill out the "New Bounce" submission form.

What if MailBounce doesn't support my list server?
Refer to the New_Server file for detailed instructions on how to submit new server formats for inclusion in upcoming releases.

MailBounce Updates

MailBounce is updated regularly. You can download the most recent version of the application from the MailBounce web site. The distributions are archived in typical file formats for the various OS platforms, and each one decompresses into its own directory or folder:

Macintosh: StuffIt archive (file extension .sit)

Windows: Zip archive (file extension .zip)

Unix: gzipped tar archive ("tarball," file extension .tgz)

Macintosh users: There is a single MailBounce application included in the standard Macintosh distribution; this application will run under both OS 9 and OS X. For OS X users who are comfortable working in the Unix shell, note that there is also a Darwin release. The OS X/Darwin distribution can be found with the other Unix distributions.

Notifications of Updates

If you would like to be informed of new MailBounce releases, then you should join one of the MailBounce announcement lists. Refer to the Announcements file for more information.

Feedback!

If you use MailBounce and like it (or even if you don't like it), please send an e-mail to Smart Mail Solutions, describing what you like (and/or dislike) about the application. User feedback is helping to continually evolve and improve MailBounce.

[home]

[ReadMe]