GreenArrow Email Software Documentation

hvmail_report Command

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%)