Secure Email Monitoring

Monitor is a web service that your computers can use to look at the results of a Batch stored on our system. A web service is a software system designed to support interoperable machine-to-machine interaction over a network.

In lay terms, your computer asks Monitor "Did this Batch work?", and Monitor answers with a Yes or No that is easy for your computer to understand (parse).

Real World Use Case

We monitor our own CheckTLS email system. We setup a Thru test to compute a total score for how well we both send and receive email. We scheduled the Batch to run every six hours.

Our hosting company uses PRTG to monitor. It uses our Monitor web service to read the LastRun and LastTotal from the Batch, and it alerts us if the test didn't run or if our score falls below 100.

This is the Batch we use: <BatchTest TestType="thru"> <Target>CheckTLS-Reply@CheckTLS.com</Target> <Delivery> <To>File</To> <Format>text</Format> </Delivery> <Total Function="average"></Total> </BatchTest>

This is the XML that Monitor outputs: <CheckTLS test="thru"> <Description>Monitor CheckTLS</Description> <LastRun>2017-02-15T14:54:12-0500</LastRun> <LastTotal>100.000000</LastTotal> </CheckTLS> Click here to fiddle with this Monitor.

Simple and fail-safe email monitoring and verification for the price of a Corporate Subscription to CheckTLS!

FailSafe Monitoring

Using Monitor and Batch, your computers can:

Accessing Batch results as a web service means any or all of the data fields available in //email/testTo: are available to your IT computer systems. You can use CheckTLS tests and tools as part of your own IT system.

Your computers use a specially formatted URL to talk directly with our computers to find out if a Batch worked. Monitor is an "active positive" test, which means everything has to work for it to report "success". If Monitor reports "success" it means three things:

Your Batch
Your Batch did all the testing you put into it and returned your requested "total" (e.g. average or minimum)
Our Tests
Our programming of all the tests and scripting you put into your Batch worked
Our Hosting
Our computers, internet, and data center are all working

If the targets in your Batch don't meet your spec, Monitor returns "unsuccessful". If CheckTLS has any internal errors or fails to run your Batch for any reasons, Monitor returns "unsuccessful". If CheckTLS is down, Monitor does not return anything, which is also "unsuccessful".

The URL your computer uses to talk to our computer includes your User Code, Password, and a BatchId. Monitor uses those to lookup the last time the Batch was run all the way thru and what the final total was. The URL also includes an AGE and a MINIMUM for success.

If the Batch last finished longer ago than the AGE that you specify, Monitor returns "unsuccessful". This prevents false positives. The Batch has to have run all the way to the end within the last AGE minutes to be successful.

If the Batch total was less than the MINIMUM, Monitor returns "unsuccessful". Monitor compares your definition of success (MINIMUM) to the total that you programmed into the Batch (see Batch documentation and edit for more information). You decide what "success" means.

Monitor Modes

Monitor has four modes: XML, CHECK, RAW, and DASHBOARD.

XML Mode

In XML mode, Monitor answers your computer with the raw AGE and TOTAL for the Batch. This lets you program your own rules for success and failure. You decide how bad a failure is and what you want to do about it. Monitor sends this XML document: <CheckTLS test="receiver"> <Description>receiver test on test@checktls.com</Description> <LastRun>2017-02-04T07:36:03-0500</LastRun> <LastTotal>100.000000</LastTotal> </CheckTLS>

The XML elements are very simple:

<CheckTLS>
The XML root node. The test attribute says the Batch was a receiver test (as opposed to a thru test).
<Description>
The Description you gave to the Batch in BatchEdit.
<LastRun>
The date and time the Batch last ran through to the very end.
<LastTotal>
The total you told the Batch to compute (total).
CHECK Mode

In CHECK mode, Monitor looks at the AGE and TOTAL of the Batch for you. It checks if the Batch finished recently enough and if it had a high enough score. You tell Monitor how long ago and what score means "success". Monitor answers your computer with a yes or no.

CHECK Formats

Monitor has three ways to tell your computer if the Batch in question was "successful":

OK/NOK
Monitor replies with a valid web page with a single line: Test OK or Test NOT OK The web page is easily parsed by your computer. The complete output looks like: <html> <head> <title>OK</title> </head> <body> Test OK </body> </html>
ONE/ZERO
Monitor replies with just a 1 or a 0. It is an invalid HTML document (i.e. no <html> tags) that looks like: 1
PASS/FAIL
Monitor reports the test result as an html document (OK/NOK) but also uses HTTP Response Headers to indicate pass/fail, like this: HTTP/1.1 412 Criteria Failed Date: Sat, 20 Jun 2026 16:25:09 -0400 Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 65718 Last-Modified: Fri, 24 Feb 2017 13:39:06 GMT Cache-Control: max-age=0 Expires: Sat, 20 Jun 2026 16:25:09 -0400 Transfer-Encoding: chunked Content-Type: text/html; charset=ISO-8859-1 <html> <head> <title>NOK</title> </head> <body> Test Not OK </body> </html>
CHECK Mode: the FailSafe Part

In all the above CHECK Formats the time that the specified batch test was run (whether or not the target(s) tested good or bad) is given in an Age: HTTP Response Header like this: HTTP/1.1 200 OK Date: Sat, 20 Jun 2026 16:25:09 -0400 Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 864000 Cache-Control: max-age=0 Expires: Sat, 20 Jun 2026 16:25:09 -0400 Transfer-Encoding: chunked Content-Type: text/html; charset=ISO-8859-1 <html> <head> <title>NOK</title> </head> <body> Test Not OK </body> </html> This shows the batch was last run to completion 10 days (864000 seconds) ago. The Age: header is the Monitor fail-safe that lets you know if your system(s) have a failure or if your test at CheckTLS has a problem.

Monitor will return a failure (NOK or 0 or http status fail) if either the Check Age or the Minimum Total parameters are not within the limits you set. But if Monitor determined that the Check Age limit was not met, then the failure is with your test at CheckTLS.

If the Age: header is new enough and Monitor returned a failure (NOK or 0 or http status fail), then your test target(s) have a problem!

Of course, XML Mode (above) makes these two choices very clear: test too old or score too low. But you may find it easier to configure your monitoring system (Nagios, PRTG, WhatsUp Gold, SolarWinds, ManageEngine, DataDog, Zabbix, HP OpenView, etc.) to parse one or more of these CHECK Formats instead of processing XML. Ideally you would program your monitoring system to turn green if Monitor returned success (OK or 1 or http status ok), yellow if Monitor returned an Age: header that was too old, and red if Monitor returned a failure (NOK or 0 or http status fail).

Show Results

By setting Show Results to "Y", you can tell Monitor to send you the output from the Batch as well. You get both the CHECK result and the Batch result. See RAW Mode below.

RAW Mode (Batch Results as a Web Service)

In RAW mode, Monitor just sends you the output from the Batch. Since this is the actual output from the Batch in the format specified in the Batch, you choose the format that your computer can parse and use. RAW mode gives you how long it's been since the test last ran successfully in the Age: header. This is computed in seconds from the Batch LastRun (date and time) field and looks like: HTTP/1.1 200 OK Date: Sat, 20 Jun 2026 16:25:09 -0400 Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.1e-fips mod_perl/2.0.9dev Perl/v5.16.3 Age: 459 ...other headers removed for clarity...

Although the RAW mode output has an HTTP header, the full RAW output is most likely not a valid HTML file because the content after the header is the raw Batch output, for example a csv batch would just be: 100 bill.g@microsoft.com 100 sjobs@apple.com 100 NoOne@NoWhere.com 100 SomeOne@SomeWhere.com 100.000 average

And for example an XML batch would be: <CheckTLS test="G_99999_99999_20251218131152" version="V03.04.00"> <Results> <Result> <Score>100</Score> <Target>test@checktls.com</Target> ...lines deleted... </Result> </Results> </CheckTLS>

RAW mode is web service access to the results of stored Batches. Since Batch unlocks options that are not available from the web site (Custom), RAW mode is web service access to these options.

See Batch Upload for how to create and/or run Batches as a web service.

DASHBOARD Mode

Output from DASHBOARD mode is a mix of webservice and normal HTML, i.e. webpage display. It only works if the result of a stored Batch is in ALERT format. ALERT format lets you define PASS (displayed in green on the DASHBOARD) and FAIL (displayed in red). (see "alert" format in Results File Format for more about ALERT format.

Monitor displays a very simple HTML webpage that looks like:

100
50
50
100
100

This page may be parsed (i.e. used as a webservice), but the format may change in the future.

DASHBOARD is designed to work intimately with a specially formatted (<Format>alerts</Format>) batch. Because the results of this batch are targeted at monitor, you will want to prevent the batch from sending resuts in email by using <To>file<</To> (or just omit the To node altogether). An example of a batch that works with DASHBOARD is: <BatchTest TestType="receiver"> <Target> DEFAULT <Suppress Function="average" Test="lt" Value="90"/> </Target> <Target>one@checktls.com</Target> <Target>two@checktls.com<</Target> <Target>three@checktls.com</Target> <Delivery> <To>file</To> <Format>alerts</Format> </Delivery> </BatchTest>

You can show only the failures on the DASHBOARD webpage by using DASHBOARD-FAILURES instead of DASHBOARD.