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 COMPANYCODE and COMPANYPASS 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 COMPANYCODE and COMPANYPASS 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.

Here is a very simple example of what can be done with our web service: Proof Of Concept.

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.

You can trial CheckTLS web services for free. While you need a Corporate Subscription to use our web services in production, you can target the domain "checktls.com" with any COMPANYCODE and COMPANYPASS (examples below).

Instructions for how to program your computer systems to communicate with a web service is beyond the scope of this documentation. The examples below demonstrate how to turn a URL for our most popular //email/testTo: into a web service and extract certain fields.

URL
https://www.CheckTLS.com/TestReceiver ?COMPANYCODE=me@mydomain.com &COMPANYPASS=IllNeverTell &EMAIL=test@CheckTLS.com &LEVEL=XML_DETAIL
 
Output
<CheckTLS test="TestReceiver"> <eMailAddress>checktls.com</eMailAddress> <ConfidenceFactor>100</ConfidenceFactor> <OutputFormat>XML_Detail</OutputFormat> <MXConfidenceFactor>90</MXConfidenceFactor> <Answer>100</Answer> <Connect>100</Connect> <HELO>100</HELO> <TLS>100</TLS> <Cert>100</Cert> <Secure>100</Secure> <From>100</From> <MXCount>1</MXCount> <MXAddrCount>1</MXAddrCount> <MX exchange="mail6.checktls.com[159.89.187.50:25]" name="mail6.checktls.com" address="159.89.187.50" port="25" preference="20"> <Answer>0.000684</Answer> <Connect>0.119217</Connect> <HELO>0.119677</HELO> <TLS>0.12012</TLS> <Cert>0.328317</Cert> <Secure>0.330249</Secure> <From>0.3502</From> <MXStep name="From">6</MXStep> <SSL> <SSLVersion>TLSv1_3</SSLVersion> <Cipher>TLS_AES_256_GCM_SHA384</Cipher> <SSLDeprecated>0</SSLDeprecated> </SSL> </MX> </CheckTLS>
 

The examples below all produce this same output:

Output
Target = test@CheckTLS.com Score = 100 MX count = 1 MX = mail4.checktls.com[10.18.112.126] MX SSL Version = TLSv1.2
 

Program source code:

Browser URL
https://www.checktls.com/TestReceiver?COMPANYCODE=me@mydomain.com&COMPANYPASS=IllNeverTell&EMAIL=test@checktls.com&LEVEL=XML_CERTDETAIL
 
Javascript
var xhttp = new XMLHttpRequest(); xhttp.open( "POST", "https://www.checktls.com/TestReceiver", true ); var formData = new FormData(); formData.append( "COMPANYCODE", "me@mydomain.com" ); formData.append( "COMPANYPASS", "IllNeverTell" ); formData.append( "EMAIL", "checktls.com" ); formData.append( "LEVEL", "XML_DETAIL" ); xhttp.onreadystatechange = function() { if (this.readyState == 4) { if (this.status == 200) { var xmlDoc = this.responseXML; console.log("ConfidenceFactor=" + xmlDoc.getElementsByTagName("ConfidenceFactor")[0].childNodes[0].nodeValue ); } } }; xhttp.send( formData ); See How to Use Embed for HTML.
 
PowerShell
$Uri = 'https://www.checktls.com/TestReceiver' $Body = @{ COMPANYCODE='me@mydomain.com' COMPANYPASS='IllNeverTell' EMAIL='test@checktls.com' LEVEL='XML_CERTDETAIL' } 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: $_" } '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 function WriteXmlToScreen ([xml]$xml) { $StringWriter = New-Object System.IO.StringWriter; $XmlWriter = New-Object System.Xml.XmlTextWriter $StringWriter; $XMLWriter.Formatting = "indented"; $xml.WriteTo($XmlWriter); $XmlWriter.Flush(); $StringWriter.Flush(); Write-Output $StringWriter.ToString(); } #WriteXmlToScreen $response
 
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( 'https://www.checktls.com/TestReceiver', [ COMPANYCODE => 'me@mydomain.com', COMPANYPASS => '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";
 
C#
using System; using System.IO; using System.Net; using System.Text; using System.Web; using System.Xml; namespace CheckTLS { class WebService { static void Main() { HttpWebRequest request = (HttpWebRequest)WebRequest.Create( "https://www.checktls.com/TestReceiver" + "?COMPANYCODE=" + WebUtility.UrlEncode("me@mydomain.com") + "&COMPANYPASS=" + WebUtility.UrlEncode("IllNeverTell") + "&EMAIL=" + WebUtility.UrlEncode("test@CheckTLS.com") + "&LEVEL=" + "XML_DETAIL" ); HttpWebResponse response = (HttpWebResponse)request.GetResponse(); if (response.StatusCode != HttpStatusCode.OK) Console.WriteLine("CheckTLS on test@CheckTLS.com" + Environment.NewLine + response.StatusCode + ": " + response.StatusDescription); StreamReader streamreader = new StreamReader(response.GetResponseStream()); String responseString = streamreader.ReadToEnd(); response.Close(); streamreader.Close(); XmlDocument xmlDoc = new XmlDocument(); xmlDoc.LoadXml(responseString); XmlNode xmlNode; xmlNode = xmlDoc.SelectSingleNode("/CheckTLS/eMailAddress"); Console.WriteLine("Target = " + xmlNode.InnerText); xmlNode = xmlDoc.SelectSingleNode("//ConfidenceFactor"); Console.WriteLine("Score = " + xmlNode.InnerText); } } }
 
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("https://www.CheckTLS.com/TestReceiver"); Map<String,Object> params = new LinkedHashMap<>(); params.put("COMPANYCODE","me@mydomain.com"); params.put("COMPANYPASS","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 ); } }

 

What Tests are Available as Web Services?

Behind the scenes, every CheckTLS webpage is available as POST to a URL. However some are not appropriate 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/testTo: (Receiver)

URL
https://www.CheckTLS.com/TestReceiver
required
format content
COMPANYCODE
text your CheckTLS Company Code
COMPANYPASS
text your CheckTLS Company Password
EMAIL
domain eMail Target
parameter
format web page prompt
LEVEL
level Output Format (must be one of XML_*)
PROGRESS
on/off Show Test in Real Time
QUICK
on/off Quick Test
CHECKMTASTS
on/off Check MTA-STS
CHECKDANE
on/off Check DANE
CHECKCERTSIGS
on/off Check Cert Sigs
RELAXWC
on/off Relax "*" match
TIMEOUT
integer SMTP TimeOut
HOST
host or IP MX Host
PORT
int MX Port
MXPREFLIMIT
int MX Pref Limit
MXENTRYLIMIT
int MX Entry Limit
MXHOSTLIMIT
int MX Host Limit
IGNORENOCONNECT
on/off Ignore No Connects
STOPAFTER
chooser Stop After
IPV4
on/off IPv4
IPV6
on/off IPv6
CHECKDNSSEC
on/off Check DNSSEC
NODNSCACHE
on/off No DNS Cache
DNSHOST
host or IP DNS Host(s)
DIRECTTLS
on/off Direct TLS
COMPELTLS
on/off Compel TLS
CHECKCRL
on/off Check CRL
CHECKOCSP
on/off Check OCSP
CACHEMIN
int Cache Minimum
CACHEMAX
int Cache Maximum
SSLVERSION
see docs SSL Version
CIPHERLIST
see docs SSL Cipher List (pre TLS 1.3)
CIPHERSUITE
see docs SSL Cipher Suite (TLS 1.3)
SENDSNI
on/off SNI
SNI
host SNI "host" to send
CACERTS
cert(s) CA Certs
AUTHTYPE
chooser SMTP AUTH Type
AUTHUSER
text AUTH User
AUTHPASS
text AUTH Pass
CHECKTLSCLIENTCERT
on/off Send CheckTLS Client Cert
CLIENTCERT
cert(s) Specific Client Cert
CLIENTKEY
key Specific Client Key
XSLURL
URL XSL URL
XSL
XML XSL to Run
SOCKS
text SOCKS (addr:port)
SMTPDetail
on/off output SMTP Detail (XML format only)
SHOWURL
on/off Show URL
RCPTTO
on/off Include RCPT TO
SENDEMAIL
on/off Send Email

//email/testMandatoryTo: (ReceiverAssureTLS)

URL
https://www.CheckTLS.com/TestReceiver
required
content
COMPANYCODE
your CheckTLS Company Code
COMPANYPASS
your CheckTLS Company Password
KEYWORDS
ASSURETLS
parameter
web page prompt

These are the same as with //email/testTo: above.

//email/testFrom: (Sender)

//email/testMandatoryFrom: (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/uploadSavedTest (BatchUpload)

The BatchUpload web service can perform four operations:

See Batch Testing and this program's documentation for specifics.

URL
https://www.CheckTLS.com/BatchUpLoad
required
content
COMPANYCODE
your CheckTLS Company Code
COMPANYPASS
your CheckTLS Company Password
parameter
web page prompt
BATCHID
Batch Id
RUNNOW
Y/N
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:

See About Monitoring and this program's documentation for specifics.

URL
https://www.CheckTLS.com/Monitor
required
content
COMPANYCODE
your CheckTLS Company Code
COMPANYPASS
your CheckTLS Company 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