GreenArrow Email Software Documentation

hvmail_generate_email_report Command

Purpose

The hvmail_generate_email_report command allows you to generate and email a summary of SMTP stats over a the time interval that you specify.

Command Syntax

USAGE
    hvmail_generate_email_report ( --start TIME --end TIME | --last PERIOD ) 
        ( --sender SENDER ) ( --background )
        ( --print | ( --subject=TEXT ) ( --from=TEXT ) ADDRESS... )
OPTIONS
    --start=TIME
    --end=TIME
    --last=PERIOD
        See documentation for logdir_select_time.
    --print
        Do not send report as email, instead print it to STDOUT.
    --subject=TEXT
        Subject of the e-mail report.
    --from=EMAILADDR
        From address of the e-mail report.
    --sender=TEXT
        Sender to limit the report to. See documentation for logfile_filter.
    --background
        Run this report in the background.
    --delay-before-report=NUMBER
	Delay for NUMBER seconds before producing the report, so that
	delivery attempts currently underway have a chance to complete
	and be included in the report. This also adds NUMBER seconds to
	the time given by the --end option.
    --num-domains=NUMBER
        List the top NUMBER domains in all of the reports. The default
        is 20.

Examples Invocations

Email a report for the past week to [email protected]:

hvmail_generate_email_report --last='1 week' [email protected]

Crontab entry to email a report covering the past 24 hours to [email protected] each day at 8 am:

0 8 * * * /var/hvmail/bin/hvmail_generate_email_report --last='1 day' [email protected]

Example Report

HVMail deliverability report
Generated: Fri Apr 20 12:06:41 2012
Data From: Fri Apr 13 12:06:41 2012 (1334336801)
       To: Fri Apr 20 12:06:41 2012 (1334941601)
============= ram-queue =============
Follow up on any domains showing a high percentage of "FAILURE", "DEFERRAL", or "CONN MAX OUT".
(Showing top 20 domains.)
                               |  TOTAL |       SUCCESS |       FAILURE |      DEFERRAL |  CONN MAX OUT
                         TOTAL |  30340 |  30313 ( 99%) |     16 (  0%) |     11 (  0%) |      0 (  0%)
test000.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test002.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test003.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test004.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test005.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test006.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test007.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test008.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test009.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test010.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test011.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test012.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test013.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test014.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test015.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test016.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test017.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test018.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test019.local.discardallmail.drh.net |   1500 |   1500 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
test001.local.discardallmail.drh.net |   1497 |   1497 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
                       drh.net |     43 |     39 ( 90%) |      4 (  9%) |      0 (  0%) |      0 (  0%)
============= bounce-queue =============
Follow up on any domains showing a high percentage of "FAILURE", "DEFERRAL", or "CONN MAX OUT".
It is common for the bounce-queue to show no remote deliveries.
(Showing top 20 domains.)
                               |  TOTAL |       SUCCESS |       FAILURE |      DEFERRAL |  CONN MAX OUT
                         TOTAL |     32 |     30 ( 93%) |      2 (  6%) |      0 (  0%) |      0 (  0%)
                  demo.drh.net |     16 |     14 ( 87%) |      2 ( 12%) |      0 (  0%) |      0 (  0%)
                       drh.net |     16 |     16 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
============= disk-queue =============
Because the disk-queue receives messages that already got a deferral error on the first 
delivery attempt, the percentage of "DEFERRAL" should be high. A high "CONN MAX OUT" 
may be normal or may be indicative of a problem, depending on the details.
(Showing top 20 domains.)
                               |  TOTAL |       SUCCESS |       FAILURE |      DEFERRAL |  CONN MAX OUT
                         TOTAL |     51 |     11 ( 21%) |      0 (  0%) |     40 ( 78%) |      0 (  0%)
                    cfl.rr.com |     45 |      6 ( 13%) |      0 (  0%) |     39 ( 86%) |      0 (  0%)
                       aol.com |      4 |      3 ( 75%) |      0 (  0%) |      1 ( 25%) |      0 (  0%)
                 drhtestgd.com |      2 |      2 (100%) |      0 (  0%) |      0 (  0%) |      0 (  0%)
============= drilldown commands =============
To diagnose the exact problem you often need to look at the exact message that the remote mail
server gave to HVMail when rejecting or deferring a message. Here are helpful commands to 
select just the data you may want to look at:
==== ram-queue
To view failures for a domain use this:
hvmail_report -q ram -s 1334336801 -e 1334941601 -c failure -r @DOMAIN.COM -a -T 40
To view deferrals for a domain use this:
hvmail_report -q ram -s 1334336801 -e 1334941601 -c deferral -r @DOMAIN.COM -a -T 40
==== bounce-queue
To view failures for a domain use this:
hvmail_report -q bounce -s 1334336801 -e 1334941601 -c failure -r @DOMAIN.COM -a -T 40
To view deferrals for a domain use this:
hvmail_report -q bounce -s 1334336801 -e 1334941601 -c deferral -r @DOMAIN.COM -a -T 40
==== disk-queue
To view failures for a domain use this:
hvmail_report -q disk -s 1334336801 -e 1334941601 -c failure -r @DOMAIN.COM -a -T 40
To view deferrals for a domain use this:
hvmail_report -q disk -s 1334336801 -e 1334941601 -c deferral -r @DOMAIN.COM -a -T 40