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
content
COMPANYCODE
your CheckTLS Company Code
COMPANYPASS
your CheckTLS Company Password
EMAIL
eMail Target
parameter
web page prompt
LEVEL
Output Format (must be one of XML_*)
PROGRESS
Show Test in Real Time
QUICK
Quick Test
CHECKMTASTS
Check MTA-STS
CHECKDANE
Check DANE
CHECKCERTSIGS
Check Cert Sigs
RELAXWC
Relax "*" match
TIMEOUT
SMTP TimeOut
HOST
MX Host
PORT
MX Port
MXPREFLIMIT
MX Pref Limit
MXENTRYLIMIT
MX Entry Limit
MXHOSTLIMIT
MX Host Limit
IGNORENOCONNECT
Ignore No Connects
STOPAFTER
Stop After
IPV4
IPv4
IPV6
IPv6
CHECKDNSSEC
Check DNSSEC
NODNSCACHE
No DNS Cache
DNSHOST
DNS Host(s)
DIRECTTLS
Direct TLS
COMPELTLS
Compel TLS
CHECKCRL
Check CRL
CHECKOCSP
Check OCSP
CACHEMIN
Cache Minimum
CACHEMAX
Cache Maximum
SSLVERSION
SSL Version
CIPHERLIST
SSL Cipher List (pre TLS 1.3)
CIPHERSUITE
SSL Cipher Suite (TLS 1.3)
SNI
SNI
CACERTS
CA Certs
AUTHTYPE
SMTP AUTH Type
AUTHUSER
AUTH User
AUTHPASS
AUTH Pass
CLIENTCERT
Client Cert
CLIENTKEY
Client Key
XSLURL
XSL URL
XSL
XSL to Run
SOCKS
SOCKS (addr:port)
SMTPDetail
SMTP Detail XML
SHOWURL
Show URL
RCPTTO
Include RCPT TO
SENDEMAIL
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