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.

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 CUSTOMERCODE and CUSTOMERPASS (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 ?CUSTOMERCODE=me@mydomain.com &CUSTOMERPASS=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:

Javascript
var xhttp = new XMLHttpRequest(); xhttp.open( "POST", "https://www.checktls.com/TestReceiver", true ); var formData = new FormData(); formData.append( "CUSTOMERCODE", "me@mydomain.com" ); formData.append( "CUSTOMERPASS", "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 = @{ CUSTOMERCODE='me@mydomain.com' CUSTOMERPASS='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', [ 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";
 
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" + "?CUSTOMERCODE=" + WebUtility.UrlEncode("me@mydomain.com") + "&CUSTOMERPASS=" + 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("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 ); } }

 

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
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_*)
QUICK
Quick Test
IGNORENOCONNECT
Ignore No Connects
PROGRESS
Show Test in Real Time
SMTPDetail
SMTP Detail XML
HOST
MX Host
PORT
MX Port
IPV4
IPv4
IPV6
IPv6
MXCOUNT
MX Count
STOPAFTER
Stop After
DIRECTTLS
Direct TLS
COMPELTLS
Compel TLS
RELAXWC
Relax "*" match
CHECKCRL
Check CRL
CHECKOCSP
Check OCSP
SSLVERSION
SSL Version
CIPHERLIST
SSL Cipher List (pre TLS 1.3)
CIPHERSUITE
SSL Cipher Suite (TLS 1.3)
XSLURL
XSL URL
XSL
XSL to Run
SMTPAUTH
SMTP AUTH Type
AUTHUSER
AUTH User
AUTHPASS
AUTH Pass
TIMEOUT
SMTP TimeOut
CACERTS
CA Certs
CLIENTCERT
Client Cert
CLIENTKEY
Client Key
RCPTTO
Include RCPT TO
SENDEMAIL
Send Email

//email/testMandatoryTo: (ReceiverAssureTLS)

URL
https://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/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:

  • 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
https://www.CheckTLS.com/BatchUpLoad
required
content
CUSTOMERCODE
your CheckTLS Customer Code
CUSTOMERPASS
your CheckTLS Customer 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:

  • 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
https://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