Types of Events
- Table of Contents
- Bounce Events
- Spam Complaint Events
- Click and Open Tracking Events (for GreenArrow Engine’s SimpleMH System)
- Unsubscribe Events (for GreenArrow Engine’s SimpleMH System)
- Delivery 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
orfailure_toolong
(as long as theReturn-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 for deactivation. bounce_all
events do not require any action and should not be a reason to remove addresses from your database or stop sending to addresses. Use the bounce_bad_address
event for subscriber deactivation instead.
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 (bounce_all ). |
bounce_all |
event_time |
The time that the bounce happened, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
email |
The email address that this message was to. | [email protected] |
listid |
The lowercased identifier for the mailing list that this message is a part of. | t99 |
sendid |
The lowercased 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 is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event back to a specific message. |
1927393 |
synchronous |
Indicates whether this was a synchronous bounce (true) or asynchronous bounce (false). | true |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
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 (bounce_bad_address ). |
bounce_bad_address |
event_time |
The time that the bounce happened, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
email |
The email address that this message was to. | [email protected] |
listid |
The lowercased identifier for the mailing list that this message is a part of. | t99 |
sendid |
For the most recent bounce in the run: The lowercased 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 is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event back to a specific message. |
1927393 |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
bounce_lite
This event is generated as a result of bounce messages processed by the Lite Bounce Processor (configured via the lite_bounce_processor_address directive).
id
integer |
The internal database identifier for this event. |
event_unique_id
string |
A universally unique identifier for this event. If you want to track an identifier for events to prevent duplicate event handling, this is the value you should use. |
event_type
string |
The type of event (in this case, |
event_time
integer |
The time the event was generated as a UNIX timestamp. |
server_id
string |
The value of the server_id configuration directive. |
bounce_code
integer |
The code of the bounce rule that this bounce matched. |
bounce_code_match_text
string |
The text within the bounce message that caused |
synchronous
bool |
Whether or not this bounce represents a synchronous bounce (i.e. was it generated during the delivery attempt’s SMTP conversation). |
report_recipient
string |
The email address that received this bounce. This is not the original message recipient email address, instead this is the email address to which this bounce was delivered. |
report_message_text
string |
If lite_bounce_processor_include_report_text is not disabled, this will be the full text of the bounce message as it was received by GreenArrow. |
Bounce Text Format
The bounce_text
field in bounce_all
and bounce_bad_address
events is calculated as follows:
- For synchronous bounces (bounces that occurred as a result of the SMTP
delivery conversation), the
bounce_text
format is the same as the Queue Logfile Format except without the conversion and replacement of ASCII bytes outside of the 33-126 range. - For asynchronous bounces (bounces that were emailed back into GreenArrow), this is the raw body of the bounce email which GreenArrow received, without multipart decoding or quoted-printable decoding.
Then:
- Bytes/octents that are not part of valid UTF-8 characters get turned into
U+FFFD
. - The length is truncated to 1024 bytes.
- This can be overridden by the store_bounce_details_length field in the Bounce Processor Configuration.
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 (scomp ). |
scomp |
event_time |
The time that the complaint was received, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
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 is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event back to a specific message. |
1927393 |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
scomp_lite
This event is generated as a result of FBL complaint messages processed by the Lite Bounce Processor (configured via the lite_fbl_processor_address directive).
id
integer |
The internal database identifier for this event. |
event_unique_id
string |
A universally unique identifier for this event. If you want to track an identifier for events to prevent duplicate event handling, this is the value you should use. |
event_type
string |
The type of event (in this case, |
event_time
integer |
The time the event was generated as a UNIX timestamp. |
server_id
string |
The value of the server_id configuration directive. |
email
string, optional |
The recipient address of the email that generated the complaint, as included in the ARF complaint report. This is information submitted as part of the FBL complaint and may not always be accurate. Also, due to forwarding or wildcarding, this may not be the email address to which you actually sent. Some FBLs will anonymize the recipient email address. For these reasons, we recommend that you instead rely on a custom header to encode recipient information. This field is typically parsed from the (optional) |
user_agent
string, optional |
The name and version of the software program that generated the report. This is information submitted as part of the FBL complaint and may not always be accurate. |
headers
hash |
The headers parsed from the complaint message as configured by the directive lite_fbl_processor_headers. Each key of the hash is the configured header name, each value is an array of strings representing each instance of that header in the original message (as received back to GreenArrow in the complaint report). |
report_recipient
string |
The email address that received this complaint. This is not the original message recipient email address, instead this is the email address to which this spam complaint was delivered. |
report_message_text
string |
If lite_fbl_processor_include_report_text is not disabled, this will be the full text of the FBL report message as it was received by GreenArrow. |
report_sender
string, optional |
The This field is parsed from the (optional) |
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 (engine_click ). |
engine_click |
event_time |
The time that the click happened, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
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_url |
The URL of the link that was clicked on. | http://www.example.com |
click_tracking_id |
The click tracking ID is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event 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. | 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 |
linkid |
The value of the user-defined link id. This field is null for links that don’t have user-defined link ids. |
12345-abcd |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
engine_open
Event
Field | Description | Example Value |
---|---|---|
event_type |
The type of event (engine_open ). |
engine_open |
event_time |
The time that the open happened, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
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 is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event 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. | Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 Lightning/4.0.1 |
is_privacy_open |
GreenArrow has determined that this open represents a Mail Privacy Protection open. | true |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
Unsubscribe Events (for GreenArrow Engine’s SimpleMH System)
If you use SimpleMH, GreenArrow Engine can process unsubscribe links via two mechanisms:
- When you insert a SimpleMH unsubscribe link, SimpleMH processes it.
- When you do not include a
List-Unsubscribe
header, SimpleMH automatically inserts one for you and processes 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 (engine_unsub ). |
engine_unsub |
event_time |
The time that the unsub happened, in seconds past the Unix epoch. | 1317305252 |
server_id |
Server ID as configured by server_id. | example |
event_unique_id |
A unique identifier for this event. | 64 character string |
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_url |
The URL of the destination unsubscribe link. For unsubscribes that occur as a result of the List-Unsubscribe header, this value will be blank. | http://www.example.com/unsub.php |
click_tracking_id |
The click tracking ID is specified using the X-GreenArrow-Click-Tracking-ID header and can be used to trace an event back to a specific message. |
1927393 |
mailclass |
If SimpleMH was used for the email, the name of the Mail Class.1 | default |
instanceid |
If SimpleMH was used for the email, the value of the InstanceID (if specified or auto-generated).1 | 12345 |
Continuing to send to an address that has unsubscribed can negatively impact 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 bounce_bad_address
event(s) can also be created.
Delivery events can 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
event_type
string |
The type of event ( |
event_time
integer |
The time that the delivery attempt happened, in seconds past the Unix epoch. |
server_id
string |
Server ID as configured by server_id. |
event_unique_id
string |
A unique identifier for this event. |
email
string |
The email address that this message was to. |
listid
string |
The identifier for the mailing list that this message is a part of. |
sendid
string |
The internal identifier for the send. |
click_tracking_id
string |
The click tracking ID is specified using the |
timestamp
float |
The time that the delivery attempt happened, in seconds past the Unix epoch. |
channel
string |
|
status
string |
Result of this delivery attempt. Can be |
is_retry
integer or boolean |
|
msguid
string |
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. |
sender
string |
The |
mtaid
string |
The identifier for the VirtualMTA / Mail Route of this message. This is set at the time of message injection. This field determines what IP address the message is delivered from.
|
mtaid_id
integer |
Primary key of the VirtualMTA that the message is assigned to. |
mtaid_name
string |
The name of the VirtualMTA that the message is assigned to. |
injected_time
integer |
The time that the message was injected into GreenArrow’s queue, in seconds past the Unix epoch. |
message
string |
The success, failure, or deferral message for this delivery attempt. This message will be in the Queue Logfile Format with non-UTF8 characters removed. |
outmtaid
integer |
Primary key of the VirtualMTA that the delivery attempt took place with. This can be, but isn’t always the same as the |
outmtaid_ip
string |
The outgoing IP address used for this delivery attempt (see note below). |
outmtaid_hostname
string |
The hostname used for this delivery attempt’s SMTP conversation (see note below). |
outmtaid_name
string |
The name of the IP address used for this delivery attempt (see note below). |
sendsliceid
string |
Internal use Studio feature that’s not yet documented. |
throttleid
integer |
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. |
mx_hostname
string |
The hostname to which this delivery attempt occurred (whether or not it came from an actual MX record). |
mx_ip
string |
The IP address to which this delivery attempt occurred (whether or not it came from an actual MX record). |
from_address
string |
The first email address in the From header as it was originally injected into GreenArrow. |
headers
object |
A JSON object containing the values of the headers as configured in the log_header configuration directive. |
message_size
integer |
The size of the message (in bytes), if loaded from storage. |
smtp_timing
string |
CSV list of SMTP timings of the delivery attempt. See the log_smtp_timings configuration directive for more information. |
bounce_code
integer |
This is the bounce code for this delivery attempt. Blank when |
source_ip
string |
The SMTP or HTTP client IP address that injected the message into GreenArrow. |
mailclass
string |
If a SimpleMH mail class was used for this message, this is that mail class.[^1] |
instanceid
string |
If a SimpleMH InstanceID was specified for this message, this is that InstanceID.[^1] |
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 equivalent.
Regarding mtaid_id
, mtaid_name
, outmtaid_ip
, outmtaid_hostname
, and outmtaid_name
: These values may be blank if the
IP address or relay server used for the attempt was deleted before the event was written
to GreenArrow’s internal database. The delivery_attempt
event is typically written to
that database within 10 seconds of the delivery attempt.