GreenArrow Documentation

Processing Events on Dedicated Servers

This is an advanced feature. Before applying any of these changes read the document carefully and make sure that you understand all the steps. If you have any questions, please contact Technical Support.

Introduction

This page describes how to configure GreenArrow to split the load of processing SimpleMH email into two groups of servers:

  • Sending Servers, which send emails.
  • Event Servers, which process clicks, opens, unsubscribes, bounces and spam complaints.

You can have one, or multiple Sending Servers and Event Servers.

This document uses the term All Servers to refer to all Sending Servers and Event Servers.

This configuration only works for SimpleMH email.

Procedure

Complete the following steps.

Update Secret Constants

Secret constants are used to create anti-tampering security codes for links and bounce messages. All Servers need to have the same “secret constants”:

  1. Choose one Sending Server, get the secret constants:

    greenarrow_config secret_constants --view
    

  2. On All Servers, set the secret constants to match:

    greenarrow_config secret_constants --constant1=INSERT_HERE --constant2=INSERT_HERE
    

  3. On All Servers: print the secret constants and verify they all match:

    greenarrow_config secret_constants --view
    

Enable Stateless Event Handling

Stateless event handling makes Sending Servers include additional information in tracking links and emails so Event Servers can process events for them.

On All Servers, run:

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

Create a Bounce Mailbox

On the Event Servers, add a new bounce mailbox.

On the Sending Servers, ensure that the bounce mailbox’s domain does NOT exist as an Incoming Email Domain.

The bounce domain’s MX records should point to the Event Servers.

Configure the Bounce Email Address on the Sending Servers

On the Sending Servers, either:

  1. Edit the Mail Classes that you are going to use with this bounce address, check “Override Default Bounce Address” and enter the bounce email address into the “Bounce Address” field.

  2. Use the X-GreenArrow-BounceMailboxOverride header to override the bounce address. This header takes precedence over the Mail Class setting.

NAT Considerations

If your servers are behind NAT, the MX record for your bounce email address domain may point to an IP address that your Sending Server can’t connect to. If this is the case, you will need to configure static routing for this domain name using the smtp_route directive.

For example, assuming your Event Server’s IP is 10.0.55.2, and your bounce address domain is bounce-domain.example.com:

  1. Add this route to the Sending Servers in /var/hvmail/control/greenarow.conf:

    ip_address * {
      domain bounce-domain.example.com {
        smtp_route 10.0.55.2
      }
    }
    

  2. Load the new configuration:

    greenarrow_config reload
    

  3. Verify that the Sending Servers can send emails to each bounce address domain on the Event Servers.

Configure Faster Delivery of Bounces

Configure SMTP Connection Reuse

On the Sending Servers:

  1. Add the following to /var/hvmail/control/greenarow.conf, replacing domain bounce-domain.example.com with your actual bounce address domain::

    ip_address * {
      domain bounce-domain.example.com {
          reuse_connections yes
      }
    }
    

  2. Load the new configuration:

    greenarrow_config reload
    

Raise the Throttle Limits

On the Sending Servers, add the bounce email address domain to all throttle templates and set the following configuration for it:

  • Max Concurrent Connections: 100
  • Max Messages per Hour: 10000000

NOTE: GreenArrow isn’t realistically going to send 10 million messages per hour over 100 connections. The reason for the 10 million message per hour limit is to set the ceiling high enough so that if bounces get created in bursts, the Sending Server can efficiently add them to the delivery backlog.

Tune the Bounce-Queue

Run these commands on the Sending Servers:

cd /var/hvmail/control
echo 100 > queue.bounce.concurrencyremote
echo 5000 > queue.bounce.limit.messages
echo 50000 > queue.bounce.ramdisk.inodes
echo 200 > queue.bounce.ramdisk.size
hvmail_init restart

Truncate Bounces at 5KB

Run this command on the Sending Servers:

echo 5120 > /var/hvmail/control/bouncemaxbytes
hvmail_init restart

Treat Bounces as “Local”

On the Event Servers, add all of the Sending Server names (as configured in /var/hvmail/control/me) to the /var/hvmail/control/opt.treat_qsbf_bounces_as_local_server_names file. Enter one name per line.

Configure URL Domains

Create each URL Domain in the following way.

On the Sending Servers:

  1. Add the URL Domain to GreenArrow’s configuration.

  2. Edit the Mail Classes that you are going to use with this URL domain, enable “Track Clicks and Opens”, and select the URL domain from the drop-down menu.

On the Event Servers

  1. Create the URL domain’s DNS records so that they point to the Event Servers.

  2. If you want to use HTTPS links for the URL Domain, then install each SSL certificate on the Event Servers.

Configure the Event Servers to Record Events

The Event Notification System is the only way you will be able to see the clicks, opens unsubscribes, bounces, and spam complaints that take place. This is because the Event Servers which process these events didn’t send the original emails, so they don’t have any Send Statistics Pages to populate.

Configure the Event Notification System on each Event Server.

Setup Feedback Loops

  1. Create a spam complaint mailbox on each Event Server.

  2. Register for feedback loops using the spam complaint mailbox created in the previous step.

Testing

We recommend testing the system before starting production sends. The following sequence is designed to catch common misconfigurations.

First, check for DNS misconfigurations:

  1. Verify that each URL domain has A or CNAME records pointing to the desired Event Servers.
  2. Verify that each incoming email domain used for bounce and spam complaint mailboxes has MX records pointing to the desired Event Servers.

Next, for each Sending Server / Event Server combination:

  1. Send an HTML email that uses click tracking and contains an unsubscribe link from the Sending Server.
  2. Load images in the email. Verify that the images load and that an engine_open event is created.
  3. Click on one of the links in the email. Verify that it redirects to the correct URL and that an engine_click event is created.
  4. Click the unsubscribe link, and verify that you’re redirected to the correct URL. If you’re using SimpleMH unsubscribe link tracking, verify that an engine_unsub event is created.
  5. Send an email containing the raw headers of the email you sent in step one to a spam complaint mailbox on the Event Server. Verify that an scomp event is created.
  6. Send an email from the Sending Server to an address that bounces. Verify that a bounce_all event is created. Depending on the type of bounce, and how GreenArrow’s bounce processor is created, this could also result in bounce_bad_address event being created.