GreenArrow Documentation

Types of Events

There are multiple kinds of events in the GreenArrow system that you can access or be notified of. This document gives an overview of each kind of event and how they relate.

Bounce Events

A bounce event is when a bounce message is received and processed by the GreenArrow Engine bounce processor.

This relates to delivery attempt events as follows:

  • If you see a delivery attempt event with a status of failure or failure_toolong (as long as the Return-Path of the message is set correctly), you will then also see a bounce event for that message.
  • If you see a delivery attempt event with a status of accepted this message may still bounce. This bounce can happen when a remote SMTP server accepts the message, then later fails at delivering it, and returns a bounce message to GreenArrow. This is called an asynchronous bounce.

A bounce event has different information on the failure than the delivery event, such as the code of the bounce processor.

There are two kinds of bounce events:

bounce_all (Previously Called hook_stat) Event

This event is triggered for every bounce message processed by the bounce processor. This includes bounces where the address has not yet met the qualifying criteria to be removed from the list. This does not require any action. In fact, you should not remove addresses from your database or stop sending to addresses based on this event. Use the bounce_bad_address event below.

This event type exists for applications that want to keep statistical information on how many bounces are received for each campaign or information on what recipients didn’t receive the email and why.

If you do not plan to use this event type, it can be turned off to reduce the overhead of processing these events.

Field Description Example Value
event_type The type of event that this is. This will be bounce_all bounce_all
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid The internal identifier for the send. t9920110705
bounce_type The type of bounce. h for hard, s for soft, and o for other. h
bounce_code The code of the type of bounce. 10
bounce_text The text of the failure message. (Up to the number of characters configured.) 1.1.1.1 failed after I sent the message. Remote host said: 554 delivery error: dd This user doesn't have a yahoo.com account ([email protected]) - mta1218.mail.mud.yahoo.com
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393

bounce_bad_address (Previously Called hook_bounce) Event

This event is triggered when the bounce processing system detects that an email address has met the configured removal threshold for either hard or soft bounces. (This often requires more than one soft bounce, as we don’t want to remove addresses after a single soft bounce.)

This event occurs so you can remove the address from your database or stop sending to this address. (Continuing to send to a bad address may have a negative impact on your deliverability.)

Field Description Example Value
event_type The type of event that this is. This will be bounce_bad_address bounce_bad_address
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
bounce_type For the most recent bounce: h for a hard bounce, and s is for a soft bounce. h
bounce_code For the most recent bounce in the run: The code of the bounce rule that this bounce matched. 10
bounce_text For the most recent bounce in the run: The text of the failure message. (Up to the number of characters configured.) 1.1.1.1 failed after I sent the message. Remote host said: 554 delivery error: dd This user doesn't have a yahoo.com account ([email protected]) - mta1218.mail.mud.yahoo.com
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393

Spam Complaint Events

When someone clicks on a “this is spam” link at an ISP that supports feedback loops, and a feedback loop notification is sent to GreenArrow, a spam complaint event is created.

This event occurs so that you can remove the address that generated the complaint from your database or stop sending to it. You can also use this event to maintain statistical information on the number of spam complaints created by each campaign. Continuing to send to an address that has complained about spam can have a negative effect on your deliverability.

scomp (Previously Called hook_scomp) Event

Field Description Example Value
event_type The type of event that this is. This will be scomp scomp
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393

Click and Open Tracking Events (for GreenArrow Engine’s SimpleMH System)

If you are using SimpleMH’s click and open tracking, then a click or open event will be created whenever someone loads images in an email message or clicks on a link in it.

If you are using GreenArrow Studio for sending, then you will receive studio_click and studio_open events, instead of engine_click and engine_open events. See GreenArrow Studio’s Types of Events documentation.

engine_click Event

Field Description Example Value
event_type The type of event that this is. This will be engine_click engine_click
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_url The URL of the link that was clicked on. http://www.example.com
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393
engine_ip The IP address that generated the click 1.2.3.4
user_agent The user agent that generated the click. Not recorded by default. See Event Notification System Configuration for how to enable recording this data. Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.89 Safari/537.36

engine_open Event

Field Description Example Value
event_type The type of event that this is. This will be engine_open engine_open
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393
engine_ip The IP address that generated the open 1.2.3.4
user_agent The user agent that generated the open. Not recorded by default. See Event Notification System Configuration for how to enable recording this data. Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 Lightning/4.0.1

Unsubscribe Events (for GreenArrow Engine’s SimpleMH System)

If you use SimpleMH, GreenArrow Engine can process unsubscribe links via two mechanisms:

  1. When you insert a SimpleMH unsubscribe link, SimpleMH will process it.
  2. When you do not include a List-Unsubscribe header, SimpleMH will automatically insert one for you and process it.

When someone unsubscribes using either of the above mechanisms, an engine_unsub event will be created.

If you are using GreenArrow Studio for sending, then you will receive studio_unsub events, instead of engine_unsub events. See GreenArrow Studio’s Types of Events documentation.

engine_unsub (Previously Called hook_unsub) Event

Field Description Example Value
event_type The type of event that this is. This will be engine_unsub engine_unsub
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid For the most recent bounce in the run: The internal identifier for the send. t9920110705
click_url The URL of the destination unsubscribe link. http://www.example.com/unsub.php
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393

Continuing to send to an address that has unsubscribed can have a negative effect on your deliverability.

Delivery Events

A delivery event represents the attempted delivery of a message through SMTP or to a local mailbox. In the case of an SMTP delivery, this shows whether the remote SMTP server accepted or rejected the message or if the delivery attempt was throttled.

When a message delivery fails bounce_all and/or bounce_bad_address event(s) can also be created.

Delivery events be logged using the delivery_attempt event type described below. Alternatively, delivery events can be viewed with the hvmail_report command or logged to a file.

delivery_attempt Event

Field Description Example Value
event_type The type of event that this is. This will be delivery_attempt. delivery_attempt
event_time The time that the bounce happened, in seconds past the Unix epoch. 1317305252
email The email address that this message was to. [email protected]
listid The identifier for the mailing list that this message is a part of. t99
sendid The internal identifier for the send. t9920110705
click_tracking_id The click tracking ID, if specified using the X-GreenArrow-Click-Tracking-ID header when the message was injected. This can be used to allow you to track back to a specific message. 1927393
timestamp The time that the bounce happened, in seconds past the Unix epoch. 1317305252.08338
channel local if the delivery attempt is to a local mailbox or remote if the delivery attempt is to a remote mail server. remote
status Result of this delivery attempt. Can be success, failure, failure_toolong, deferral or connmaxout. success
is_retry 0 if this is the first delivery attempt and 1 otherwise. 0
msguid Internal unique ID of the message. IDs are not repeated unless the system clock goes backward. This is not the same as the Message-ID. 1490817966.30790899
sender The Return-Path of the message. This is also called the envelope sender, MFROM address or bounce address. [email protected]
mtaid Primary key of the VirtualMTA that the message is assigned to. 2
injected_time The time that the message was injected into GreenArrow’s queue, in seconds past the Unix epoch. 1490817966
message The success, failure, or deferral message for this delivery attempt. 207.99.125.72 accepted message./Remote host said: 250 ok 1490817966 qp 13613/
outmtaid Primary key of the VirtualMTA that the delivery attempt took place with. This can be, but isn’t always the same as the mtaid. For example, if mtaid is a Routing Rule, then outmtaid will be the VirtualMTA within that Routing Rule that was actually used for the delivery attempt. 2
sendsliceid Internal use Studio feature that’s not yet documented. 298602
throttleid Blank if the delivery attempt took place using an SMTP Relay Server or the default Throttling Rule. Otherwise, it contains the ID of the Throttling Rule that was used when making the delivery attempt. 35

A more detailed description of the timestamp through throttleid fields in the above list can be found in the Delivery Event Processed Logfile Format documentation. Note that that document’s clicktrackingid and this document’s click_tracking_id are equivelant.

 Event Notification System
Legacy Types of Events