Email Check API - Technical documentation

As JSON:

{
 "decoded": "foo@xn—blmchen-o2a.de", 
 "extSyntax":1 
 "result":1, 
}

result

Tests the syntax of the address against the e-mail addressing standards, possible result values are

• 0: invalid syntax
• 1: valid syntax
• 2: probably valid syntax, Unicode problems were solved, see decoded

The test is stricter than the standards because it requires a valid domain name in the address. Localhost addresses and other exotic cases will not be accepted, because it is unlikely that these are e-mail addresses valid for business.

If the syntax result is 0 (invalid) or 2 (probably valid) the structure contains also syntax warnings explaining the problems, see below.

decoded

If the syntax test ended with a result of 2, this field will contain the decoded ASCII address. A syntax test result of 2 means that the address contained Unicode characters (e.g., umlauts, arabic or chinese characters), which are invalid in an e-mail address. These characters were successfully converted and the resulting, valid ASCII address was stored in decoded. Further tests should always use this decoded address.

The decoding during the syntax test is done in two stages:

1. the local part of the address is checked for German umlauts. If found, they are converted to their usual ASCII counterparts (ü - ue, ä - ae, ö - oe, ß - ss)
2. the domain part of the address is transformed to Punycode, according to the standard for international domains

extSyntax

Many e-mail providers have their own rules for valid e-mail addresses of their domains. These typically include the minimal length of an address, which punctuation characters are allowed etc. The extended syntax check verifies addresses against these rules. Possible results are:

• 0: invalid syntax for this domain
• 1: valid syntax for this domain

If the extended syntax check fails, the result structure will include syntax warnings explaining the problem, see below.

syntaxWarnings

If one of the syntax checks fails, the result structure will include one ore more syntaxWarnings elements:

<syntaxStatus> 
 ... 
 <syntaxWarnings>synm002</syntaxWarnings> 
 <syntaxWarnings>.... 
</syntaxStatus>

domainScores

The domainScores element consists of a list of similar sounding domain names ordered by a calculated score:

<syntaxStatus> 
 ... 
 <domainScores>
  <domainScore>
   <domain>teleos-web.de</domain><score>1.0</score>
  </domainScore> 
 </domainScores> 
</syntaxStatus>

Result

As XML:

<qualityStatus> 
 <address>0</address> 
 <bounceRisk>0</bounceRisk> 
 <checked>1</checked> <decoded>foo@xn—blmchen-o2a.de</decoded> 
 <domain>1</domain> 
 <extSyntax>1</extSyntax>   
 <mailserver>0</mailserver> 
 <mailserverDiagnosis>0</mailserverDiagnosis> 
 <probability>0</probability> 
 <syntax>2</syntax> 
</qualityStatus>

{ 
 "address":0, 
 "bounceRisk":0, 
 "checked":1, 
 "decoded": 
 "foo@xn—blmchen-o2a.de", 
 "domain":1, 
 "extSyntax":1 
 "mailserver":0, 
 "mailserverDiagnosis":1, 
 "probability":0, 
 "syntax":1, 
}

We will discuss the results in the order of execution of the respective tests:

<qualityStatus> 
 ...
 <syntaxWarnings>synm002</syntaxWarnings> 
 <syntaxWarnings>.... 
</qualityStatus>

<qualityStatus> 
 ... 
 <domainScores>
  <domainScore>
   <domain>teleos-web.de</domain><score>1.0</score>
  </domainScore>
 </domainScores> 
</qualityStatus>

Functionality

This section describes the execution of the address quality check in detail. The check consist of the following steps:

1. checking the mailbox (local part) of the address for Unicode characters. Unicode is not allowed in the local part, so this routine only checks for typical, language-specific typos. Currently this includes only German umlauts. If found, they are converted to their usual ASCII counterparts: ü - ue, ä - ae, ö - oe, ß - ss. If at least one of these conversions happens, the syntax warning synm018 is added to the result, and the decoded ASCII value of the mailbox is stored in decoded.

2. checking the domain name of the address for Unicode characters. If Unicode is found, the domain is probably an IRI, and the domain name will be transformed according to the Punycode standard (RFC 3942). In this case the syntax warning synm017 is added to the result, and the decoded ASCII value of the domain name is stored in decoded.

3. if decoded contains a value this address will be used for all subsequent tests, else the original address.

4. checking the syntax according to the standards. As mentioned above, exotic cases, like localhost addresses or addresses with comments, will be rejected. It expects real addresses usable for e-mail transfer accross domains. If the snytax check fails, the test assumes an input error and result includes a list of similar sounding, popular domain names.

5. checking the syntax against the rulebase of extended syntax criteria. These are provider-specific syntax rules that can be changed over time.

6. checking the domain name. The component looks for a DNS (A) record for the domain. By default the component tries 2 times, with a timeout of 2 seconds each, before giving up. In case of failure the mentioned list of similar domain names is returned.

7. looking for a mailserver. Using the DNS information from the previous step, the component looks for MX entries for the domain. By default the component tries 2 times, with a timeout of 2 seconds each, before giving up. In case of failure the mentioned list of similar domain names is returned.

8. calculating the bounce risk from historic data contains an aggregation of previous e-mail transfers for various domains. If there were more than 80% bounces then the bounce risk is considered high, in all other cases it is normal.

9. calculating the domain name probability, if there are domains with similar names having higher address counts. If there are such domains, then an input error is assumed, and the list of similar domains is included in the result.

10. check the SMTP cache for the domains status. The SMTP cache tracks all SMTP test results and tries to find out whether a SMTP test for an address is appropriate. Some mailservers are set up to always answer positively or negatively when asked for a mail addresses. Others might have technical errors or be simply too slow. In all these cases it would be not useful to start a SMTP check. So the address check would be skipped. The SMTP cache contains also lists of exceptions for domains and mailservers that provide fixed answers.

11. check the SMTP cache for an already existing Greylisting result. This step only occurs in the enhanced quality check. Results of Greylisting background checks are temporarily stored because it could be computationally expensive to repeat the test. By default these results ares stored for 24 hours. If during the storage time one of the stored addresses is checked again, the SMTP results from the cache are used. Although these results are taken from the cache, the checked flag is set to 1 (really checked), because the cache content is the result from a recent SMTP check.

12. checking the address by contacting the mailserver. If the SMTP cache doesnt object, a SMTP conversation with one of the mailservers for the domain is initiated.

13. the response behaviour of the domains mailservers is diagnosed. If the address check was skipped due to the SMTP cache, the value from the cache will be returned, else the result of the SMTP check will be used

Address spam trap check

<spamtrapStatus> 
 <infoId>foo@bar.com</infoId> 
 <result>1</result> 
 <trapType>1</trapType> 
</spamtrapStatus>

{"infoId": "foo@bar.com", "result": 1}

<spamtrapInfo> 
 <id>foo@bar.com</id> 
 <trapType>1</trapType> 
 <owner>Spamtrap ... GmbH</owner> 
 <remarks>Sending to spam traps of this kind leads to the following reactions ...</remarks> 
 <url>spam110trap.de/x1</url> 
</spamtrapInfo>

{ 
 "id":"foo@bar.com", 
 "trapType":1, 
 "owner":"Spamtrap ... GmbH", 
 "remarks":"Sending to spam traps of this kind leads to the following reactions ...", 
 "url":"spam110trap.de/x1" 
}

<robinsonlistStatus> 
 <infoIds>
  <infoId>ecg-liste</infoId> 
 </infoIds> 
 <result>1</result> 
</robinsonlistStatus>

{"infoIds": ["ecg-liste"], "result": 1}

<robinsonlistInfo>
 <country>A</country> 
 <id>ecg-liste</id> 
 <name>ECG-Liste</name> 
 <owner>RTR GmbH</owner> 
 <remarks></remarks> 
 <url>http://www.rtr.at/de/tk/E_Commerce_Gesetz</url> 
</robinsonlistInfo>

{ 
 "country":"A", 
 "name":"ECG-Liste", 
 "id":"ecg-liste", 
 "owner":"RTR GmbH", 
 "remarks":"", 
 "url":"http://www.rtr.at/de/tk/E_Commerce_Gesetz" 
}

<publicServiceDomainStatus> 
 <infoIds>
  <infoId>5000</infoId> 
 </infoIds> 
 <result>1</result> 
</publicServiceDomainStatus>

{"infoIds": [5000], "result": 1}

<publicServiceDomainInfo> 
 <addressCity>München, Landeshauptstadt</addressCity> 
 <addressState>Bayern</addressState> 
 <addressZipCode>80331</addressZipCode> 
 <countryCode>de</countryCode>
 <description>Kreisfreie Stadt</description> 
 <id>5335</id> 
 <orgName>München, Landeshauptstadt</orgName> 
</publicServiceDomainInfo>

{ 
 "addressStreet":null, 
 "addressCity":"München, Landeshauptstadt", 
 "addressZipCode":"80331", 
 "addressState":"Bayern", 
 "countryCode":"de", 
 "description":"Kreisfreie Stadt", 
 "id":5335, 
 "orgName":"München, Landeshauptstadt" 
}

<no-advertising> 
 <result>1</result> 
</no-advertising>

{"result":1}

<mailserverDiagnosisInfo> 
 <result>2</result> 
</mailserverDiagnosisInfo>

{"result": 2}

<languageStatus> 
 <result>1</result> 
 <languages>
  <language>en</language> 
 </languages> 
</languageStatus>

{"result": 1, "languages": ["en"]}

<iwtStatus> 
 <infoId>bar.com</infoId> 
 <result>1</result> 
</iwtStatus>

{"infoId": "bar.com", "result": 1}

<iwtInfo> 
 <id>bar.com</id> 
 <owner>Webmailer Corp.</owner> 
 <country>USA</country> 
 <orientation>1</orientation> 
 <languages>
  <language>en</language> 
 </languages> 
</iwtInfo>

{ 
 "id": "bar.com", 
 "owner": "Webmailer Corp.", 
 "country“: "USA“, 
 "orientation“:1, 
 “languages“:["en"] 
}

<genderStatus> 
 <avgage>57.1</avgage> 
 <detail>3</detail> 
 <firstname>Herbert</firstname> 
 <nameday>2013-03-16</nameday> 
 <result>1</result> 
</genderStatus>

{"avgage": 57.1, "detail":3, "firstname":"Herbert", "nameday": "2013-16-03" "result":0}

<educationDomainStatus> 
 <infoId>bar.com</infoId> 
 <result>1</result> 
</educationDomainStatus>

{"infoId": "bar.com", "result": 1}

<educationDomainInfo> 
 <addressAreaCode>6421</addressAreaCode> 
 <addressCity>Marburg</addressCity> 
 <addressFax>967-411</addressFax> 
 <addressHomePage>www.bar.com</addressHomePage> 
 <addressPhone>967-431</addressPhone> 
 <addressPostbox></addressPostbox> 
 <addressStreet>Dürerstraße 2011</addressStreet> 
 <addressZipCode></addressZipCode> 
 <countryCode>de</countryCode> 
 <domains>
  <domain>bar.com</domain> 
 </domains> 
 <foundationYear>1909</foundationYear> 
 <orgName>Evangelische Hochschule Bar</orgName> 
 <orgSubtype>Theologische Hochschule</orgSubtype> 
 <orgType>Fachhochschulen und Hochschulen ohne Promotionsrecht</orgType> 
 <rightDoctorate>false</rightDoctorate> 
 <rightHabilitation>false</rightHabilitation> 
 <shortName>Marburg EH Bar</shortName> 
 <sponsorship>privat, staatlich anerkannt</sponsorship> 
 <state>Hessen</state> 
 <students>69</students> 
<educationDomainInfo>

{ 
 "addressAreaCode":"6421", 
 "addressCity":"Marburg", 
 "addressFax":"967-411", 
 "addressHomePage":"www.bar.com", 
 "addressPhone":"967-431", 
 "addressPostbox":"", 
 "addressStreet":"Dürerstraße 2011", 
 "addressZipCode":"" "countryCode":"de", 
 "domains": ["bar.com"], 
 "foundationYear":1909, 
 "orgName":"Evangelische Hochschule", 
 "orgType":"Fachhochschulen und Hochschulen ohne Promotionsrecht", 
 "orgSubtype":"Theologische Hochschule", 
 "rightDoctorate":false, 
 "rightHabilitation":false, 
 "shortName":"Marburg EH Bar", 
 "sponsorship":"privat, staatlich anerkannt", 
 "state":"Hessen" 
 "students":69, 
}

<disposableStatus> 
 <infoId>bar.com</infoId> 
 <result>1</result> 
</disposableStatus>

{"infoId": "bar.com", "result": 1}

<disposableInfo> 
 <country>USA</country> 
 <id>bar.com</id> 
 <owner>Dosposabil</owner> 
 <remarks>No sign-in necessary</remarks> 
 <validity>3T</validity> 
<disposableInfo>

{ 
 "country":"USA", 
 "id":"bar.com", 
 "owner":"Dosposabil", 
 "remarks":"No sign-in necessary", 
 "validity":"3T" 
}

<companyDomainStatus> 
 <infoId>bar.com</infoId> 
 <result>1</result> 
</companyDomainStatus>

{"infoId": "bar.com", "result": 1}

<companyDomainInfo> 
 <id>bar.com</id> 
 <orgName>Bar.Com GmbH</orgName> 
 <addressStreet>Barstrasse 11</addressStreet> 
 <addressCity>Neumarkt</addressCity> 
 <addressZipCode>92318</addressZipCode> 
 <addressLatitude>11.000001</addressLatitude> 
 <addressLongitude>49.111110</addressLongitude> 
 <countryCode>de</countryCode> 
 <classifications>
  <classification>
   <id>34.10</id>
    <description>Herstellung von Kraftwagen und Kraftwagenteilen</description>
   <lang>de</lang>
  <type>wz2003</type>
  </classification> 
 </ classifications> 
<companyDomainInfo>

{ 
 "id":"bar.com", 
 "orgName":"Bar.Com GmbH", 
 "addressStreet":"Barstrasse 11", 
 "addressCity":"Neumarkt", 
 "addressZipCode":"92318", 
 "countryCode": "de", 
 "addressLatitude": 11.000001, 
 "addressLongitude": 49.111110, 
 "classifications": [ 
  {"id":"34","text":"Herstellung von Kraftwagen und Kraftwagenteilen", "type": "wz2003", "lang": "de"} 
 ] 
}

<crRiskStatus> 
 <result>1</result> 
</crRiskStatus>

{"result": 1}

<crRiskStatus> 
 <result>1</result> 
</crRiskStatus>

{"result": 1}

<botriskStatus> 
 <infoIds>
  <infoId>2</infoId>
  <infoId>3</infoId> 
 </infoIds> 
 <result>1</result> 
</botriskStatus>

{"infoIds": [2, 3], "result": 1}

<botRiskInfo> 
 <botriskType>1</botriskType> 
 <id>1</id> 
 <owner>A botrisk provider name</owner> 
 <remarks>Details about the bot, its maintainer</remarks> 
 <url>http://bot-maintainer.com</url> 
</botRiskInfo>

{ 
 "botRiskType": 1, 
 "id": 1, 
 "owner": "A botrisk provider name", 
 "remarks": "Details about the bot, its maintainer", 
 "url": "http://bot-maintainer.com" 
}

<blacklistStatus> 
 <infoId>bar.com</infoId> 
 <listType>2</listType> 
 <result>1</result> 
</blacklistStatus>

{"infoId": "bar.com", "listType": 2, "result": 1}

<blacklistInfo> 
 <id>abuse</id> 
 <listType>2</listType> 
 <owner/> 
 <remarks>Administrative address for problem reports with a domain</remarks> 
 <url/> 
</blacklistInfo>

{ 
 "id": "abuse", 
 "listType": 2, 
 "owner": "", 
 "remarks": "Administrative address for problem reports with a domain", 
 "url": "" 
}

<roleStatus> 
 <result>1</result> 
</roleStatus>

{"result": 1}