Getting Started with Event Notification

This page is an introduction to the GreenArrow Event Notification System.

Table of Contents
Introduction
The Basics
Event Delivery Methods
Event Delivery Formats
- Delivery Methods Other than SQL
- SQL Delivery Method
Available Events
Example Configurations
Troubleshooting
Further Reading

Introduction

The act of sending an email message using the GreenArrow platform can result in a number of events that can be recorded by the platform. Those events might include:

One or more attempts to deliver the message to its destination.
Successful or unsuccessful delivery of the message.
The recipient opening the message and possibly clicking on one or more links in the message.
The recipient reporting the message as spam and/or unsubscribing from future messages from the sender.

While GreenArrow collects these events for display in the platform UI and/or retrieval by either the Engine or Studio API, the Event Notification System is the only way for GreenArrow users to also collect the events for use in third-party applications, such as Business Intelligence tools, in-house dashboards, and other uses. If the Event Notification System is not configured using the methods described here and elsewhere, then no delivery events will be collected by GreenArrow for post-processing use.

The Basics

The core of the Event Notification System is the Event Processor, which is configured using event_delivery_destination directive stanzas in the greenarrow.conf file. Each such directive allows you to specify the type(s) of events to collect, the method for collecting them, and the destination for this collection. Furthermore, multiple stanzas are supported, so it’s possible to “mix and match” your event collection configuration, with different destinations collecting different types of events using different methods, something we’ll illustrate below.

Event Delivery Methods

Several delivery methods are supported for the Event Notification System. Multiple methods can be specified in a single greenarrow.conf file, and multiple destinations for the same method are also suppored, so long as each method/destination pair is declared in its own stanza.

HTTP/HTTPS endpoints

The event_delivery_url directive allows you to specify a URL that will accept HTTP or HTTPS POST transactions, as is typical for webhooks.

Local logfiles

The event_delivery_logfile directive allows you to specify a logfile as the destination for events, with the logfile written in a format you choose from a list of supported formats (see below). This logfile can then be subject to further processing by third-party or other tools as you see fit.

SQL database servers

The event_delivery_sql_dsn directive gives you the ability to write events directly to a SQL database server. With this directive, you’ll specify the database connection information, a username and password, and a SQL INSERT statement to use to put event data into the database.

Forked-off processes

The event_delivery_pipe_command directive allows you to specify an external command for GreenArrow to execute, with the Event Notifier writing the events to the STDIN of the command.

Event Delivery Formats

Delivery Methods Other than SQL

For the HTTP(S) POST, logfile, and forked-off process event delivery methods, you have the choice of several different formats to use, with JSON being the default. The format is set by the event_delivery_format directive in the event_delivery_destination stanza. Other choices are form (HTTP(S) POST only), CSV, and a few versions of processed logs that mimic the formats available in the deprecated Delivery Attempt Log

SQL Delivery Method

Rather than specifying a delivery format for the SQL Delivery Method, the event_delivery_sql_binds directive is used to specify which event data fields to bind to the SQL INSERT statement associated with this directive.

Available Events

GreenArrow makes a number of different events available to the Event Notification System, and you can pick and choose which ones you want, either with the event_delivery_events configuration directive or the event_delivery_sql_event directive, depending on the event delivery format chosen.

Example Configurations

Below are some example configurations for the Event Delivery Notification system.

HTTPS POST of All Events

event_delivery_destination primary {
  event_delivery_url "https://mywebhook.example.com"
  event_delivery_events all
}

Click, Open, and Unsubscribe Events Written to a Local Logfile

event_delivery_destination local_log {
  event_delivery_logfile "/var/hvmail/log/myevents.log"
  event_delivery_events engine_click, engine_open, engine_unsub, studio_click, studio_open, studio_unsub
  event_delivery_format json
}

Open Events Written to a SQL Database

event_delivery_destination destination-sql-server {
  event_delivery_events all
  event_delivery_sql_dsn dbi:Pg:dbname=greenarrow;host=127.0.0.1
  event_delivery_sql_event engine_open, studio_open {
    event_delivery_sql_query "INSERT INTO opens_archive ( id, event_type ) VALUES ( ?, ? ) ON CONFLICT DO NOTHING"
    event_delivery_sql_binds id, event_type
  }
}

It’s worth noting here that the names assigned to the event_delivery_destination stanzas above, specifically “primary”, “local_log”, and “destination-sql-server”, are arbitrarily chosen. We could’ve just as easily shown them with the names “Larry”, “Moe”, and “Curly”, and you can choose whatever name(s) make the most sense to you.

Also, as noted above, more than one directive for the Event Notification System can appear in a greenarrow.conf file, so if you need events sent to one or more webhooks, plus a local logfile, and a SQL database server, you can do that.

This example shows three event_delivery_destination directives from the same configuration file:

# All delivery events written to /var/hvmail/log/allEvents.log in JSON format
#
event_delivery_destination all_events_log {
  event_delivery_logfile "/var/hvmail/log/allEvents.log"
  event_delivery_events all
  event_delivery_format json
}

# Click and open events written to /var/hvmail/log/engagementEvents.log in CSV format
#
event_delivery_destination engagement_events_log {
  event_delivery_logfile "/var/hvmail/log/allEvents.log"
  event_delivery_events engine_click, engine_open, studio_click, studio_open
  event_delivery_format csv
}

# Complaints written to a pipe for processing by a Python program to remove duplicates
#
event_delivery_destination dedupe {
  event_delivery_pipe_command /var/hvmail/local/scripts/complaint-deDupe.py
  event_delivery_events scomp, scomp_list
  event_delivery_format json
  event_delivery_pipe_batch_duration 5s
  event_delivery_pipe_ack_mode exit_status
}

Troubleshooting

If events aren’t being written to their destination as expected, the /var/hvmail/log/event-processor2/current logfile may contain clues as to why, as in these two examples:

@4000000067a5234126cfbcd4 destination(primary) failed to connect: Post "https://mywebhook.example.com": dial tcp: lookup mywebhook.example.com  on 1.1.1.1:53: no such host
@4000000067a52374365d2ed4 destination(primary) failed to connect: Post "https://mywebhook.example.com:8765": dial tcp 205.159.93.168:8765: connect: connection refused

And sometimes the act of reloading your configuration might turn up errors before you can even start trying to collect events:

# greenarrow_config reload
Updated database with latest configuration.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING: event_processor_logfile /var/hvmail/logz/myevents.log
directory (/var/hvmail/logz) does not exist
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!