hvmail_report Command
- Table of Contents
- Purpose
- Command Syntax
- Examples
Purpose
The hvmail_report command allows you to access the SMTP delivery attempt event logfiles. You can select a number of different report types, as well as selecting what time frame you want to see data for.
Currently there is no web-interface for the hvmail_report command, although one is planned. Much of this data can be seen from the current web-interface in GreenArrow Engine, on a per-send basis.
Command Syntax
USAGE
hvmail_report OPTIONS...
OPTIONS
SELECTING WHICH QUEUE
You must specify this option:
-q,--queue=QUEUE
Read logfile data from the QUEUE HVMail queue. This can be
either "ram", "bounce", "disk", or "all".
SELECTING TIME RANGE
Specify either these two options:
-s,--start=TIME
The time to start reading the logfile data at.
-e,--end=TIME
The time to end reading the logfile data at.
or this option:
-l,--last=PERIOD
Reads the logfile data from "PERIOD ago" to "now". If this
is used then --start and --end must not be specified.
FUTHER SELECTING THE DATA
You may give any of these options. Different options logically
combine together in an AND fashion. While multiple of the same
options combine together in an OR fashion.
-f,-S,--sender=ADDRESS
Only include data on delivery attempts where the envelope
sender of the message (a.k.a. return path) is the same
as ADDRESS. This option may be specified multiple times,
and data on all senders specified will be included. Address
wildcarding supported; see below.
-r,--recipient=ADDRESS
Only include data on delivery attempts where the recipient
is the same as ADDRESS. This option may be specified
multiple times, and data on all recipients specified will
be included. Address wildcarding supported; see below.
-c,--status=STATUS
Only include data on delivery attempts that resulted in the
status code of STATUS. STATUS may be "success", "failure",
"deferral", or "connmaxout".
-m,--mtaid=MTAID
Only include data on delivery attempts that were a part of
the VirtualMTA named MTAID.
-i,--sendid=SENDID
Only include data on delivery attempts that were part of
the Send identified with SENDID.
--listid=LISTID
Only include data on delivery attempts that were identified
with the listid of LISTID.
WHICH REPORT
You must give one of these options:
-d,--by-domain
Create a report listing deliverability statistics broken
down by domain.
-t,--by-time
Create a report listing deliverability statistics broken
down by time.
-g,--raw-logfile
Output the raw logfile data.
-a,--delivery-attempts (-A,--show-address) (--show-time)
(-M,--show-mtaid) (-O,--show-outmtaid)
Create a report with one line for each delivery attempt
showing the status code and the reason for that status
code, including any message given by a remote SMTP
server. Optionally specify the --show-address option to
include the recipient address of the delivery attempt in
the report. Optionally specify the --show-time option to
include the time that each delivery attempt included in
the report. Optionally specify the --show-mtaid option
to include the mtaid and sendid of each delivery attempt
included in the report.
--processed-logfile (--human)
Output the processed logfile data. Optionally specify
--human to get a more human-readable output.
SELECTING HOW MUCH OF THE REPORT
You may give either of these options:
-H,--head=NUMBER
Print only the first NUMBER lines of data from the report.
-T,--tail=NUMBER
Print only the last NUMBER lines of data from the report.
OTHER OPTIONS
--no-header
Do not print the header describing the selected time period.
--help
Show this guide.
TIME FORMATS
TIME is in the format:
@4000000043cc4645005ea86c
A TAI64N date.
1137460830
A date in seconds since the UNIX epoch, 00:00:00 1970-01-01 UTC.
'now'
'5 minutes ago'
'1 day ago'
'Sun Jan 1 17:00:00 CST 2006'
'1/1/06 5:00pm'
'1/1/06 1 day ago'
'1/1/06 1 day'
'Mon, 16 Jan 2006 19:25:34 -0600'
Any date format understood by the date(1) command using the
-d option.
PERIOD is in the format:
'1 day'
'5 minutes'
'1 day 6 hours'
'10 seconds'
Any string that can have "ago" appended and will be understood
by the date(1) command using the -d option.
For more information about time formats, at a shell run: "info date",
then select "options for date", then select "*Note Date input formats"
under the explanation of the -d option.
ADDRESS WILDCARDING
An e-mail address given to the --sender or --recipient command above
may be a wildcard pattern in two ways:
Any address specified in the format "@domain.com" will match any e-mail
address at "domain.com".
An address may contain an asterisk ("*") to match any collection
of zero or more characters. There may be only one asterisk in an
address. This asterisk may be in the local or remote part of the
address, and may be combined with the previous form of wildcarding.
Here are some examples of valid wildcard patterns:
@aol.com
user*@whatever.com
@*.net
something@*
Addresses are matched case-insensitively.
VERP addresses and patterns in the qmail format "[email protected]@[]"
are handled as they should be: The pattern of "[email protected]@[]"
is translated internally to the pattern "local*@domain.com", and an
address in the logfiles of "[email protected]@[]" is translated to
"[email protected]" before matching.
Selecting a Queue
The queue option (-q) determines what data you will get.
| Queue | Description |
|---|---|
ram |
Contains first delivery attempts for messages injected into GreenArrow. |
disk |
Contains subsequent delivery attempts for each message. (Except that deliveries to local domain names stay in the ram or bounce queue. They are not moved to the disk queue like remote/SMTP deliveries.) |
bounce |
Contains first delivery attempts for internally created messages. |
If you choose the all option for the queue parameter in hvmail_report, then all of the delivery attempts from the ram queue will be printed, then all of the delivery attempts from the bounce queue, then all of the delivery attempts from the disk queue -- so the individual delivery attempts may not be printed in order.
Selecting a Date Range
hvmail_report is only able to provide reports if the data still exists in the log files. The logs hvmail_report pulls from are rotated based on the amount of disk space allocated to delivery logs.
If you see output like this (showing some time missing) it means you’re requesting a report for a time frame when the logs no longer exist:
Starting = requested Sun Sep 6 13:43:00 2015
ACTUAL==> Wed Dec 31 18:00:00 1969
missing 215552 seconds
You will need to change the date range you’re searching for to a more recent date.
If you want to have more logs stored moving forward (allowing you to request older delivery logs) you’ll need to increase the amount of disk space allocated to delivery logs.
Examples
All delivery attempts in the last 5 minutes
hvmail_report -q all --last '5 min' -a --show-address --show-mtaid --show-time | sort
2011-10-04 12:41:58.899789500 failure <[email protected]> mtaid=<> sendid=<>: Sorry, no mailbox here by that name. (#5.1.1)/
2011-10-04 12:41:58.914615500 success <[email protected]> mtaid=<> sendid=<-ic>: did 0+1+0/qp 20641/
2011-10-04 12:41:59.583560500 success <[email protected]> mtaid=<> sendid=<-ic>: 64.21.76.32 accepted message./Remote host said: 250 ok 1317750119 qp 31968/
2011-10-04 12:42:41.034958500 success <[email protected]> mtaid=<> sendid=<>: 64.21.76.32 accepted message./Remote host said: 250 ok 1317750161 qp 32152/
Delivery attempts for a specific email address
hvmail_report -q all --last '1 hour' -a --show-address --show-mtaid --show-time --recipient [email protected]
2011-10-04 12:00:03.627125500 success <[email protected]> mtaid=<> sendid=<>: 64.21.76.32 accepted message./Remote host said: 250 ok 1317747603 qp 26579/
Percentage of delivery attempts succeeded/failed/deferred by domain
hvmail_report -q ram --last '6 min' --by-domain -H20
| TOTAL | SUCCESS | FAILURE | DEFERRAL | CONN MAX OUT
TOTAL | 1375 | 961 ( 69%) | 7 ( 0%) | 13 ( 0%) | 394 ( 28%)
yahoo.com | 710 | 315 ( 44%) | 2 ( 0%) | 10 ( 1%) | 383 ( 53%)
hotmail.com | 228 | 227 ( 99%) | 1 ( 0%) | 0 ( 0%) | 0 ( 0%)
gmail.com | 159 | 159 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
aol.com | 53 | 45 ( 84%) | 0 ( 0%) | 0 ( 0%) | 8 ( 15%)
msn.com | 29 | 29 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
sbcglobal.net | 24 | 23 ( 95%) | 1 ( 4%) | 0 ( 0%) | 0 ( 0%)
cox.net | 9 | 9 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
live.com | 6 | 6 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
comcast.net | 5 | 5 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
Note: The above command can be helpful to judge system speed. If you take the total number of messages in the past 6 minutes and multiply by 10 you have a number that is messages/hour. Selecting just the first delivery attempts give you a good idea how fast messages are entering GreenArrow from the injecting system.
Here’s another example that targets a specific time range:
hvmail_report -q all --start='Wed Feb 4 7:00:00 CST 2015' --end='Wed Feb 4 8:00:00 CST 2015' --by-domain -H20
| TOTAL | SUCCESS | FAILURE | DEFERRAL | CONN MAX OUT
TOTAL | 2635488 | 1922469 ( 72%) | 47815 ( 1%) | 366361 ( 13%) | 298843 ( 11%)
yahoo.com | 608249 | 446474 ( 73%) | 64 ( 0%) | 126572 ( 20%) | 35139 ( 5%)
gmail.com | 339686 | 339319 ( 99%) | 66 ( 0%) | 301 ( 0%) | 0 ( 0%)
aol.com | 286883 | 209497 ( 73%) | 23 ( 0%) | 53828 ( 18%) | 23535 ( 8%)
bellsouth.net | 181431 | 19135 ( 10%) | 20 ( 0%) | 23225 ( 12%) | 139051 ( 76%)
hotmail.com | 151652 | 151142 ( 99%) | 42 ( 0%) | 468 ( 0%) | 0 ( 0%)
comcast.net | 118547 | 80407 ( 67%) | 30523 ( 25%) | 0 ( 0%) | 7617 ( 6%)
cox.net | 108471 | 50769 ( 46%) | 10 ( 0%) | 38782 ( 35%) | 18910 ( 17%)
sbcglobal.net | 67552 | 61833 ( 91%) | 13 ( 0%) | 5082 ( 7%) | 624 ( 0%)
charter.net | 63522 | 14025 ( 22%) | 9 ( 0%) | 20454 ( 32%) | 29034 ( 45%)
msn.com | 59696 | 59516 ( 99%) | 7 ( 0%) | 173 ( 0%) | 0 ( 0%)
att.net | 54968 | 43995 ( 80%) | 163 ( 0%) | 50 ( 0%) | 10760 ( 19%)
if.inboxfirst.com | 51860 | 51860 (100%) | 0 ( 0%) | 0 ( 0%) | 0 ( 0%)
verizon.net | 41950 | 41444 ( 98%) | 20 ( 0%) | 14 ( 0%) | 472 ( 1%)
windstream.net | 23808 | 8554 ( 35%) | 117 ( 0%) | 5101 ( 21%) | 10036 ( 42%)
juno.com | 21311 | 7304 ( 34%) | 892 ( 4%) | 12757 ( 59%) | 358 ( 1%)
earthlink.net | 17979 | 15456 ( 85%) | 123 ( 0%) | 541 ( 3%) | 1859 ( 10%)
embarqmail.com | 14510 | 6565 ( 45%) | 2 ( 0%) | 28 ( 0%) | 7915 ( 54%)
live.com | 11513 | 11407 ( 99%) | 5 ( 0%) | 43 ( 0%) | 58 ( 0%)
me.com | 9576 | 7269 ( 75%) | 13 ( 0%) | 3 ( 0%) | 2291 ( 23%)