Lite Bounce Processor

Table of Contents
Introduction
Comparison & Contrast to the Full Bounce Processor
Configuration
- Mail Class
- Example Configuration
Service and Logfile

Introduction

The Lite Bounce Processor is an alternative to GreenArrow’s Full Bounce Processor.

The Lite Bounce Processor does the following:

Processes synchronous & asynchronous bounces.
Processes spam complaints.
Generates bounce_lite and scomp_lite events when bounces and spam complaints can be successfully parsed.
Forwards the bounce or spam complaint to a configurable email address when the bounce or spam complaint cannot be successfully parsed (if configured).

Comparison & Contrast to the Full Bounce Processor

The Lite Bounce Processor gives you access to the raw nuts-and-bolts, while the Full Bounce Processor is a more fully managed solution. Specifically:

The Lite Bounce Processor:

For bounces:
- Requires you to set the the Mail From (the RFC5321.MailFrom) of the email, encoding whatever identifying information you want for the email.
- When processing a bounce message, provides back to you the Mail From (the RFC5321.MailFrom) of the bounced email along with the bounce reason code.
For spam complaints:
- When processing an ARF spam complaint notification, provides back to you any headers of the original email you request and the Mail From (the RFC5321.MailFrom) if made available in the ARF report.
- This requires that you encode whatever information you want to get back in the headers and/or RFC5321.MailFrom of the email.

The Full Bounce Processor:

Automatically sets the Mail From (the RFC5321.MailFrom), overriding any value you may have set.
Automatically adds headers in the email needed for processing spam complaints.
When processing bounces and spam complaints, in the bounce and spam complaint events, provides you with the original email address, InstanceID, Click-Tracking-ID, and other metadata about the original message — this is calculated from the automatically set RFC5321.MailFrom and automatically added headers.

The Lite Bounce Processor does not do the following:

Repeat Bounce Counting

If you intend on using GreenArrow’s Marketing Studio bounce processing, you don’t want the Lite Bounce Processor.

See the Example Configuration section below for how you might integrate with the Lite Bounce Processor.

Configuration

The Lite Bounce Processor is configured with the following directives:

Mail Class

In most cases, if you’re using the Lite Bounce Processor, you probably don’t want GreenArrow to replace your 5321.MailFrom address or add its X-Mailer-Info / X-Mailer-Info-Extra headers.

To prevent this behavior, disable the Handle Bounce & FBL option on the mail class.

Example Configuration

In the example below:

Process as a bounce any email to an address that looks like this (made-up) VERP format /^b-[0-9a-fA-F]{8}-[0-9a-fA-F]{16}@[^@]*$/, regardless of whether or not the domain name is configured as an Incoming Email Domain.
Process as a complaint any email that matches /^fbl@[^@]*$/ to an Incoming Email Domain.
Any scomp_lite events generated will include the X-CampaignID and X-SubscriberID headers from the original message, so long as they’re provided in the complaint report.
If a message arrives at a matching address and the message can’t be parsed by GreenArrow, the message will be forwarded to the lite_bounce_processor_forward_errors_to or lite_fbl_processor_forward_errors_to address accordingly.

general {
    lite_bounce_processor_address /^b-[0-9a-fA-F]{8}-[0-9a-fA-F]{16}@[^@]*$/ local_domains_only=yes
    lite_bounce_processor_forward_errors_to "[email protected]"
    lite_fbl_processor_address /^fbl@[^@]*$/ local_domains_only=yes
    lite_fbl_processor_headers "X-CampaignID", "X-SubscriberID"
    lite_fbl_processor_forward_errors_to "[email protected]"
}

To use the above configuration, your integration would do the following:

Your injector would inject messages with a MAIL FROM (RFC5321.MailFrom) of something that matches /^b-[0-9a-fA-F]{8}-[0-9a-fA-F]{16}@[^@]*$/ and encodes campaign/recipient information. The first hex number would contain the Campaign ID and the second hex number would contain the Subscriber ID for the email. The domain name would need be a domain name that has MX records that direct incoming email to the GreenArrow server.
Your injected messages would include the headers X-CampaignID and X-SubscriberID, containing your Campaign ID and Subscriber ID for the email.
Your FBLs would be configured to addresses that match /^fbl@[^@]*$/.
Your bounce_lite event processor would parse information from bounce_lite.report_recipient to connect bounce_lite events back to the original campaign/recipient.
Your scomp_lite event processor would parse information from the X-CampaignID and X-SubscriberID headers to connect scomp_lite events back to the original campaign/recipient.

Service and Logfile

Bounces and spam complaints are processed and logged by the same service. To monitor this service’s log file, execute the following command:

tail -F /var/hvmail/log/bounce-processor2/current | tai64nlocal

The Lite Bounce Processor is run from the /service/hvmail-bounce-processor2 service.

To temporarily turn off the bounce processor, run:

svc -d /service/hvmail-bounce-processor2

Be aware that leaving the Lite Bounce Processor down for an extended period of time can cause its queue to fill, leading to backpressure on the delivery queue, which can cause GreenArrow to stop delivering mail.

To turn it back on run:

svc -u /service/hvmail-bounce-processor2

To check whether the service is on, run:

hvmail_init status | grep hvmail-bounce-processor2

To check the size of the Lite Bounce Processor queue:

hvmail_status status

In hvmail_status status, you’ll see the following lines:

Lite bounce processor queue:      0% used (     0/  3000) soft limit
                                  0% used (     0/  5000) hard limit

If the soft limit is met or exceeded, delivery will be slowed. If the hard limit is met, no further messages will be added to the queue until some are processed. This can cause GreenArrow to stop delivering mail.