Web Service (API)

The CheckTLS Application Programming Interface (API) makes select CheckTLS.com tests and tools available as web services.

What is a Web Service?

According to W3C:
A web service is a software system designed to support interoperable machine-to-machine interaction over a network.

Web services are only available to Corporate Subscribers and require CUSTOMERCODE and CUSTOMERPASS parameters on every use. Protect these credentials in the programming you use to call our web services! If you embed them in a web page, anyone can right click and view source to steal your corporate password.

CheckTLS web services are available for testing and proof-of-concept without a subscription. Without a subscription, any CUSTOMERCODE and CUSTOMERPASS will work but testing is limited to the single address "test@checkts.com".

Why Use a Web Service?

You can run our tests on your data directly from your computer systems without any human interaction, without a browser and without a keyboard or screen. You can use our feature functionality into your own email systems, data processing, data analytics, mobile apps, etc. You can put your own skin on CheckTLS and embed it in your intranet, web pages, mashups, blogs, etc. In other words, you can use CheckTLS as if you had our computer code in your systems.

Our services are simple enough that we have not formalized them with SOAP, WSDL, or UDDI, nor do we offer an orthogonal REST-ful interface. CheckTLS web services are simple POSTs to URLs that return results in XML.

How Do You Use a Web Service?

A CheckTLS web service provides XML data to a data requestor (you) as a result of an HTTP POST. The URL of the POST determines what test is being requested, and the FIELDS in the POST provide the input(s) to the test.

Instructions for how to program your computer systems to communicate with a web service is beyond ths scope of this documentation. We do provide sample programs that call our most popular //email/Test To: and extract several data items:

Output
All these sample programs produce exactly the same output:
Target = test@CheckTLS.com
Score = 100
MX count = 1
MX = mail4.checktls.com[10.18.112.126]
MX SSL Version = TLSv1.2
PowerShell
$Uri = 'http://www.checktls.com/TestReceiver'
$Body = @{
	CUSTOMERCODE='me@mydomain.com'
	CUSTOMERPASS='IllNeverTell'
	EMAIL='test@CheckTLS.com'
	LEVEL='XML_DETAIL'
}
Try {
	[xml]$response = Invoke-RestMethod -Uri $Uri -Method Post -Body $Body -ContentType 'application/x-www-form-urlencoded' -ErrorAction Stop
} Catch {
	Write-Warning "ERROR: Could not fetch CheckTLS result, error: $_"
}
'Target = ' + $response.CheckTLS.eMailAddress
'Score = ' + $response.CheckTLS.ConfidenceFactor
'MX count = ' + @($response.CheckTLS.MX).Count
Foreach( $mx in $response.CheckTLS.MX ) {
	'MX = ' + $mx.exchange
	'MX SSL Version = ' + $mx.SSL.SSLVersion
}
'MX1.Cert1.Subject.commonName = ' + @(@($response.CheckTLS.MX)[0].SSL.Certs.Cert)[0].Subject.commonName
Perl
#!/usr/bin/perl -w
use strict;
use LWP::UserAgent;
use HTTP::Request::Common;
use XML::XPath;

my $ua = LWP::UserAgent->new;
my $request = POST( 'http://www.checktls.com/TestReceiver', [
	CUSTOMERCODE =>	'me@mydomain.com',
	CUSTOMERPASS =>	'IllNeverTell',
	EMAIL =>	'test@CheckTLS.com',
	LEVEL =>	'XML_DETAIL',
] );
my $response = $ua->request($request);
unless( $response->is_success) {
     print $response->status_line;
}
my $XML = $response->content();
my $xp = XML::XPath->new(xml => $XML);
print 'Target = ' . $xp->find('/CheckTLS/eMailAddress') . "\n";
print 'Score = ' . $xp->find('/CheckTLS/ConfidenceFactor') . "\n";
my $nodeset = $xp->findnodes('/CheckTLS/MX');
print 'MX Count = ' . $nodeset->get_nodelist() . "\n";
foreach my $mx ($nodeset->get_nodelist()) {
	print 'MX = ' . $mx->find('@exchange') . "\n";
	print 'MX SSL Version = ' . $mx->find('SSL/SSLVersion') . "\n";
}
print 'MX1.Cert1.Subject.commonName = ' . $xp->find('/CheckTLS/MX[1]/SSL/Certs/Cert[1]/Subject/commonName') . "\n";
Java
import javax.xml.parsers.*;
import javax.xml.xpath.*;
import org.w3c.dom.*;
import java.io.*;
import java.net.*;
import java.util.*;

public class webservice {

	public static void main(String[] args) throws Exception {

		URL url = new URL("http://www.CheckTLS.com/TestReceiver");
		Map<String,Object> params = new LinkedHashMap<>();
		params.put("CUSTOMERCODE","me@mydomain.com");
		params.put("CUSTOMERPASS","IllNeverTell");
		params.put("EMAIL","test@CheckTLS.com");
		params.put("LEVEL","XML_DETAIL");
		StringBuilder postData = new StringBuilder();
		for (Map.Entry<String,Object> param : params.entrySet()) {
			if (postData.length() != 0) postData.append('&');
			postData.append(URLEncoder.encode(param.getKey(),"UTF-8"));
			postData.append('=');
			postData.append(URLEncoder.encode(String.valueOf(param.getValue()),"UTF-8"));
		}
		byte[] postDataBytes = postData.toString().getBytes("UTF-8");
		
		HttpURLConnection connection = (HttpURLConnection)url.openConnection();
		connection.setRequestMethod("POST");
		connection.setRequestProperty("Content-Type","application/x-www-form-urlencoded");
		connection.setRequestProperty("Content-Length",String.valueOf(postDataBytes.length));
		connection.setDoOutput(true);
		connection.getOutputStream().write(postDataBytes);;
		InputStream ins = connection.getInputStream();

		DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
		DocumentBuilder dBuilder;
		dBuilder = dbFactory.newDocumentBuilder();
		Document doc = dBuilder.parse(ins);
		XPathFactory xpFactory = XPathFactory.newInstance();
		XPath xp = xpFactory.newXPath();

		System.out.println("Target = " + xp.evaluate("/CheckTLS/eMailAddress", doc, XPathConstants.STRING));
		System.out.println("Score = " + xp.evaluate("/CheckTLS/ConfidenceFactor", doc, XPathConstants.STRING));
		NodeList nList = (NodeList)xp.evaluate("/CheckTLS/MX", doc, XPathConstants.NODESET);
		System.out.println("MX count = " + nList.getLength());
		for (int n=0; n<nList.getLength(); n++) {
			Element eMX = (Element) nList.item(n);
			System.out.println("MX = " + eMX.getAttribute("exchange"));
			Element eSSL = (Element) eMX.getElementsByTagName("SSL").item(0);
			System.out.println("MX SSL Version = " + eSSL.getElementsByTagName("SSLVersion").item(0).getTextContent());
		}

		System.exit( 0 );
	}

}
browser
http://www.CheckTLS.com/TestReceiver?CUSTOMERCODE=me@mydomain.com&CUSTOMERPASS=IllNeverTell&EMAIL=test@CheckTLS.com&LEVEL=XML_DETAIL

What Tests are Available as Web Services?

Behind the scenes, every CheckTLS webpage is available as POST to a URL. However some are not apropriate as web services (e.g. Login), and some do not yet have the option to return results as XML. Those web pages that are available as web services are documented below. We are adding XML output to more and more of our webpages, so if a test is not listed below, check back later or Contact Us to request we add it.

//email/Test To: (Receiver)

URL
http://www.CheckTLS.com/TestReceiver
required
content
CUSTOMERCODE
your CheckTLS Customer Code
CUSTOMERPASS
your CheckTLS Customer Password
parameter
web page prompt
EMAIL
eMail Address
LEVEL
Output Format (must be one of XML_*)
HOST
MX Host
PORT
MX Port
COMPELTLS
Compel TLS
RELAXWC
Relax "*" match
SSLVERSION
SSL Version
SENDEMAIL
Send Email
AUTH
AUTH Type
AUTHUSER
AUTH User
AUTHPASS
AUTH Pass
TIMEOUT
SMTP TimeOut
CACERTS
CA Certs
SENDCC
Send Client Cert
CLIENTCERT
Client Cert
CLIENTKEY
Client Key

//email/test Mandatory To: (ReceiverAssureTLS)

URL
http://www.CheckTLS.com/TestReceiver
required
content
CUSTOMERCODE
your CheckTLS Customer Code
CUSTOMERPASS
your CheckTLS Customer Password
KEYWORDS
ASSURETLS
parameter
web page prompt
These are the same as with //email/Test To: above.

//email/Test From: (Sender)

//email/Test Mandatory From: (SenderAssureTLS)

As both Sender tests are executed in response to an email you send, there is no web service necessary. To automate a Sender test, just have your system automatically generate the Sender test email.

//email/upload saved test (BatchUpload)

The BatchUpload web service can perform four operations:

  • update stored BatchTests
  • run stored BatchTests
  • update and run stored BatchTests (at once)
  • run an ad-hoc BatchTest (one-time, not saved)
  • See Batch Testing and this program's documentation for specifics.

    URL
    http://www.CheckTLS.com/BatchUpload
    required
    content
    CUSTOMERCODE
    your CheckTLS Customer Code
    CUSTOMERPASS
    your CheckTLS Customer Password
    parameter
    web page prompt
    BATCHID
    Batch Id
    RUNNOW
    Run Now Id
    XMLFILE
    XML File
    XML
    XML
    These parameters are only available if Batch Id is "new":
    DESCRIPTION
    Description
    DAYOFMONTH
    Day of Month
    DAYOFWEEK
    Day of Week
    HOUROFDAY
    Hour of Day
    MINUTEOFHOUR
    Minute of Hour

    //email/monitor

    The Monitor web service can perform three operations:

  • show how to use Monitor
  • show the output of a Monitor call
  • show the URL "code" to make a Monitor call
  • See About Monitoring and this program's documentation for specifics.

    URL
    http://www.CheckTLS.com/Monitor
    required
    content
    CUSTOMERCODE
    your CheckTLS Customer Code
    CUSTOMERPASS
    your CheckTLS Customer Password
    parameter
    web page prompt
    BATCHID
    Batch Id
    MODE
    Monitor Mode
    These parameters are only available if Monitor Mode is "check":
    AGE
    Check Age
    TOTAL
    Minimum Total
    FORMAT
    "FORMAT" Format
    RESULTS
    Show Results