Delivery Event Processed Logfile Format
This document defines the “processed logfile format” which contains log entries of each delivery attempt event.
You get access to this by running the
hvmail_report command with the
The processed logfile format contains a single line for each delivery attempt event.
Each line contains a tab-separated set of columns. Each column’s data is guaranteed to not to contain any tabs. There is no escape character or line continuation character.
Columns of the processed logfile format
The columns are as follows:
Time of delivery attempt in seconds since the Unix epoch.
||delivery to locally handled email address (i.e. local mailbox)|
||delivery to remote email address via SMTP|
Result of this delivery attempt.
||delivery failed due to explicit rejection|
||delivery failed due to being in the queue longer than the allowed time (due to deferrals or connmaxout errors)|
||delivery deferred for later retry|
||delivery attempt prevented by throttle (this attempt would have put us over the throttle limits)|
||this is a retry delivery attempt (i.e. this message was already tried before but the attempt resulted in a deferral or a connmaxout)|
||this is the first delivery attempt for this message|
There are rare occurrences of where this value is
1 for a delivery attempt that is not a retry, due to the internal bouncer queue being full and overflowing messages to a different queue. THis will only happen for internally created messages (which always have a SendID ending in
-ic). This should only happen if your system is under extreme pressure to process a large number of bounce messages or forwarded messages, which are also bouncing or forwarding.
Internal unique ID of message. These are not repeated unless the system clock goes backwards.
Even through this looks like a floating point number, it is a string. To compare values you must use a string comparison. For example the message ID
12.34 is NOT the same as
12.340 since these are different strings.
Recipient email address of message.
Return-Path of email message (also called envelope sender, MFROM address, or bounce address.)
MTAid / VirtualMTA / Mail Route of message. This determines what IP address the message is delivered from.
Internal send identifier of message. This determines which group this message belongs to.
Mailing list identifier of this message.
(11) injected time
Time in seconds past the Unix epoch that this message was created.
Success, failure, or deferral message for this delivery attempt.
Newlines in the message are replaced with the
/ character, null and backspace characters (hex
1e) are replaced with an underscore (
_), and tabs are replaced with spaces.
If this delivery attempt was through SMTP (channel=remote), this is the primary key of the IP Address or Relay Server that was used to deliver this message.
You can see the primary keys by looking at the number at the end of the URL for the
View page of each VirtualMTA in the GreenArrow Engine web interface, or by looking at the
id columns of the
mr_relay tables in PostgreSQL.
Not yet documented.
This field is blank if the delivery attempt took place using an SMTP Relay Server or the default throttling rule.
Otherwise this field contains the ID of the Throttling Rule that was used when making the delivery attempt.
This field contains the value of the
X-GreenArrow-Click-Tracking-ID header, if present. Otherwise it is left blank.
Here is an example delivery attempt event:
|Column number||Column name||Example Data|
Messages with multiple recipients
If a message is injected to multiple recipients, there will be one msguid for that message. (The msguid is unique to the message.) Since each delivery attempt for each recipient will be logged, you can have multiple log entries for each msguid. In this case, you would want to use the
recipient field to differentiate between these different results.
Note: we may add a field to this logfile format that will track the number of the recipient for the message, so it would be easier to differentiate between results for different recipients. or we may change the msguid field to be specific to the recipient and not the
# date | /var/hvmail/bin/mailsubj test1 firstname.lastname@example.org email@example.com
# hvmail_report -q ram –last ‘1 min’ –processed-logfile
1317240923.22286 remote success 0 1317240923.67920340 firstname.lastname@example.org email@example.com 1317240923 184.108.40.206 accepted message./Remote host said: 250 ok 1317240923 qp 25956/ 2 35 1234
1317240924.03923 remote success 0 1317240923.67920340 firstname.lastname@example.org email@example.com 1317240923 220.127.116.11 accepted message./Remote host said: 250 ok 1317240924 qp 25962/ 2 35 1235
You can see how each line has the same msguid.
--processed-logfile option is useful for scripting, but isn’t easily read by humans. The
--human option can be added in combination with
--processed-logfile to make it a bit more human-friendly.
Here is an example of both covering the same data:
date | /var/hvmail/bin/mailsubj test1 firstname.lastname@example.org
# hvmail_report -q ram --last '1 min' --processed-logfile 1428427817.05678 remote success 0 1428427816.76031064 email@example.com firstname.lastname@example.org 1428427816 18.104.22.168 accepted message./Remote host said: 250 ok 1428427817 qp 15219/ 2
# hvmail_report -q ram --last '1 min' --processed-logfile --human timestamp=<1428427817.05678> channel=<remote> status=<success> is_retry=<0> msguid=<1428427816.76031064> recipient=<email@example.com> sender=<firstname.lastname@example.org> MTAid=<> SendID=<> ListID=<> injected_time=<1428427816> message=<22.214.171.124 accepted message./Remote host said: 250 ok 1428427817 qp 15219/> outmtaid=<2> SendSliceID=<> throttleid=<> clicktrackingid=<>