Bounce Recovery

• Table of Contents
• Overview
• Two methods to filter bounces
• Subcommands
  • list
  • reactivate_simplemh
  • reactivate_studio
  • unsupress_studio
  • check_simplemh
• Options
  • Timestamp Format
  • Universal Options
• Data Sources
• Multi-Server Installations
• Example Usages
  • List and Review the Affected Records with an Intermediary File
  • Update Records Directly
  • Rollback bounce_bad_address Events

Overview

Sometimes a mailbox provider will inadvertently send out an inaccurate bounce message. For example, on December 14-15, 2020, Google sent out “The email account that you tried to reach does not exist” bounces for valid email addresses. This caused some email addresses sent to during this time to be considered bad and deactivated.

The greenarrow bounce_recovery command is used to recover from this kind of incident by reactivating these email addresses.

Two methods to filter bounces

There are two methods you can use to select bounces to take corrective action on.

(1) You can search for bounces using these options:

• --start and --end to specify a time range.
• --bounce-regexp to specify a regular expression that the bounce message must match.
• --domain to specify one or more domains that the email addresses must be at

(These are documented in detail below.)

For example, this will reactivate in Studio bounces on January 5th containing the “oops” in the error message at aol.com:

greenarrow bounce_recovery reactivate_studio --start "2020-01-05 00:00" --end "2021-01-06 00:00" --domain aol.com --bounce-regexp="oops"

(2) External filtering using the list subcommand and --source-csv

You can also use the list subcommand to create a CSV file of matching bounces, filter that with whatever tools you prefer, and then feed it back into this tool for processing using the --source-csv option.

For example:

greenarrow bounce_recovery list --start "2020-01-05 00:00" --end "2021-01-06 00:00" > /tmp/bounce_records.all
cat /tmp/bounce_records.all | grep -i @aol.com | grep oops > /tmp/bounce_records.filtered
greenarrow bounce_recovery reactivate_studio --source-csv < /tmp/bounce_records.filtered

You could then use the same list of bounces for the other two reactivation subcommands:

greenarrow bounce_recovery reactivate_simplemh --source-csv < /tmp/bounce_records.filtered
greenarrow bounce_recovery unsuppress_studio --source-csv < /tmp/bounce_records.filtered

This method also provides a way to review the data before taking any corrective action.

Subcommands

The following subcommands to greenarrow bounce_recovery are available.

list

The list subcommand prints a list of affected email addresses in CSV format to stdout.

The listing contains one entry for each time an email address was detected as bad (a bounce_bad_address event) so a single email address may occur multiple times in the listing.

# greenarrow bounce_recovery list --start "2020-12-01 00:00" --end "2021-01-01 00:00"
email,listid,badaddressid
[email protected],a5004,512
[email protected],a5004,513
[email protected],a5004,514
[email protected],a5004,515
[email protected],a5004,516
[email protected],a5004,517
[email protected],a5004,518
[email protected],a5004,519
8 record(s) were found

The above command searches all email addresses marked as bad due to bounces from the start of December until the end of the year. In the case as above where no time zone is specified, the system time zone is used.

reactivate_simplemh

The reactivate_simplemh subcommand removes the affected email addresses from SimpleMH Bad Address Suppression.

# greenarrow bounce_recovery reactivate_simplemh --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 record(s) were removed from bounce_bad_addresses (the SimpleMH suppression list)

reactivate_studio

The reactivate_studio subcommand reactivates the affected subscribers in Studio.

# greenarrow bounce_recovery reactivate_studio --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 subscriber(s) were reactivated

unsupress_studio

GreenArrow provides options at both the system and organization level to automatically add email addresses that are removed due to bounces to suppression lists.

If you use either of these options, you can remove those addresses from the suppression lists they were automatically added to with the unsupress_studio subcommand.

This does not remove the email address from all suppression lists, just the suppression lists that they were automatically added to due to the bounce in question.

Here is an example:

# greenarrow bounce_recovery unsuppress_studio --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 suppression list entries were removed
(note: if both the global and per-organization suppression auto-bounce suppression
lists are enabled then each email may result in two suppression list entries being removed)

check_simplemh

The check_simplemh subcommand searches the SimpleMH Bad Address Suppression database for entries created for an email or email/ListID combination due to bounces.

An email address is required:

# greenarrow bounce_recovery check_simplemh [email protected]
That email address was found in SimpleMH bad address suppression on the following listids:
 * list1

You may also optionally specify a ListID after the email address:

# greenarrow bounce_recovery check_simplemh [email protected] list1
That email address was found in SimpleMH bad address suppression on the following listids:
 * list1

Options

The options listed in sections below tell greenarrow bounce_recovery what operations to perform and how to format its output. The options can go in any order.

Timestamp Format

The time-related options (--start and --end) accept data in the following format:

2006-01-02 15:04:05 UTC

The second and timezone fields are optional, so this example is also valid:

2006-01-02 15:04

All other fields are mandatory:

• The seconds field defaults to 0.
• The timezone defaults to the system timezone.

Universal Options

The following command-line parameters are available to the greenarrow bounce_recovery subcommands (excluding the check_simplemh command, described above):

Data Sources

This tool can obtain the list of email addresses to update from GreenArrow’s database or a CSV file.

The list subcommand prints a CSV file to stdout. If you want to capture this, review it, edit it, and then apply it to the destructive commands below - the generated CSV file is acceptable as input to this tool.

Multi-Server Installations

The command reads from a database table written to by the local bounce processor

• not the delivery attempt log. That means that if a message bounces on server A, but that bounce gets processed by server B, server B will have the data that greenarrow bounce_recovery reads from, and server A will not.

Example Usages

Below we describe two ways to use the bounce recovery command.

List and Review the Affected Records with an Intermediary File

To review and optionally edit the list of affected email addresses before making any changes to the database, write them to an intermediary file:

# greenarrow bounce_recovery list --start "2020-12-01 00:00" --end "2021-01-01 00:00" > reactivation.txt
8 record(s) were found

You could then review the list of addresses to see if there’s any you’d like to exclude. To exclude them, delete them from the file.

Then, you can pipe that file into the recovery command, adding the --source-csv option and removing the time ranges.

# greenarrow bounce_recovery reactivate_simplemh --source-csv < reactivation.txt
8 record(s) were removed from bounce_bad_addresses

# greenarrow bounce_recovery reactivate_studio --source-csv  < reactivation.txt
8 subscriber(s) were reactivated

# greenarrow bounce_recovery unsuppress_studio --source-csv < reactivation.txt
8 address(es) were removed from suppression list(s)

Update Records Directly

If you’re not interested in reviewing the email addresses before modifying the database, you can skip writing to an intermediary file and rely on GreenArrow to do the right thing.

We recommend at a minimum calling the list command first to review the impact:

# greenarrow bounce_recovery list --start "2020-12-01 00:00" --end "2021-01-01 00:00"
email,listid,badaddressid
[email protected],a5004,512
[email protected],a5004,513
[email protected],a5004,514
[email protected],a5004,515
[email protected],a5004,516
[email protected],a5004,517
[email protected],a5004,518
[email protected],a5004,519
8 record(s) were found

Then you can move forward with the updates:

# greenarrow bounce_recovery reactivate_simplemh --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 record(s) were removed from bounce_bad_addresses

# greenarrow bounce_recovery reactivate_studio --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 subscriber(s) were reactivated

# greenarrow bounce_recovery unsuppress_studio --start "2020-12-01 00:00" --end "2021-01-01 00:00"
8 address(es) were removed from suppression list(s)

Rollback bounce_bad_address Events

If you’re using the Event Notification System, you may have an external application that deactivated subscribers when bounce_bad_address events were created. If so, you can use the list subcommand to obtain a list of addresses to reactivate in CSV format. You can optionally add on the --include-sendid argument to include SendIDs in the output. For example:

greenarrow bounce_recovery list --start "2020-12-01 00:00" --end "2021-01-01 00:00" --include-sendid