Real Time Verification API Documentation

Transcription

1 Real Time Verification API Documentation Release checker.com February 27, 2016

2

3 Contents 1 Product Overview Product Overview Quick Start Quick Start Features Features Technical Specification Technical Specification Installation Installation Configuration And Usage Configuration And Usage Integration Integration Plugins Plug-ins FAQs Frequently Asked Questions Status Codes Verification Response Codes For API V Integration Examples Integration Examples Glossary Glossary i

4 ii

5 Note: This is version 1 endpoint documentation maintained for customers migrating from the following providers: -checker.com yoyo.com cleansing.com bulk verifier.com For customers using our API for the first time, please see our most up to date Verification API. Our verification API will help your business reduce costs by eliminating bad addresses from entering your information systems. Contents 1

6 2 Contents

7 CHAPTER 1 Product Overview 1.1 Product Overview Why Address Verification? Sending s to non-existent addresses is never a good idea for many reasons including: Damaging the reputation of your ESP infrastructure (IP addresses) Many ESPs will have maximum hard bounce thresholds. Exceed these and your account could be closed. Bad s in a list negatively affects deliver-ability rates A Block List can keep track of failed deliveries (e.g. bad address) at a particular domain. Too many failed deliveries can raise some flags thus raising the risk of your campaign being flagged as spam. Processing hard bounces means wasted time An sent to a bad or non-existent address results in a bounce message coming back. Someone or something (e.g. automated software) is required to remove the bounces from a list so as to avoid sending to bad addresses next time. Tip: Cleansing bad s from a list using verification technology before embarking on an ing campaign significantly reduces the above challenges Product Description hippo.com offers data cleansing services specifically for addresses. Offering a fully cloud based solution, hippo.com provides fast, reliable and accurate verification. With unrivalled coverage in all areas (including traditionally hard to verify addresses such as Hotmail and Yahoo), hippo.com is the natural choice for customers requiring good coverage in their applications for both B2B and B2C addresses Possible Applications for Address Verification API If you operate a lead generation web site, blog or forum make it harder for users to sign up with false s. For e-commerce checkouts, make sure customers receive their order notifications by preventing invalid s from being entered. If your call centre takes addresses as part of the customer contact data, real-time verification can greatly reduce the amount of incorrectly keyed ed addresses. 3

8 For software vendors where addresses are captured as part of the on-boarding process, integrate full verification as a value-add for your service. With hippo.com, there is no need any more to take incorrect addresses and wait for them to bounce! How To Get Started To get started request a trial key. 4 Chapter 1. Product Overview

9 CHAPTER 2 Quick Start 2.1 Quick Start This quick start guide is designed to get you up and running as fast as possible. Please follow the steps below in sequence: ) Get a License Key Request a trial key ) Try it! Plug your license key into the following Paste the url above into your browser and watch the response come back as follows: { "status":"bad", "additionalstatus":"mailboxdoesnotexist", " addressprovided":"[email protected]", " addresschecked":"[email protected]", " addresssuggestion":"" Note: Internet Explorer may prompt to download the file instead of simply displaying it on screen. This is a quirk of Internet Explorer and not an issue with the API. We do not recommend Internet Explorer for testing with the API. Instead, use Chrome or Firefox - both will display the results on screen correctly! ) Next Steps Configuration And Usage Integration 5

10 6 Chapter 2. Quick Start

11 CHAPTER 3 Features 3.1 Features > 99.9% Service Availability Fully load balanced and automatic fail-over systems dispersed across multiple data centers in multiple regions deliver enterprise grade resilience Fanatical Service Quality Management (SQM) hippo.com operational staff obsessively monitor services to ensure the best possible uptime and coverage. Uptime and functional correctness is actively monitored on a minute by minute basis from multiple data centers dispersed across North America, Europe and South East Asia Multi Factor Verification Progressive verification using multiple verification processes including: Syntax checking DNS checking Mailbox checking Unrivalled Coverage With more than 5 years experience and the benefit of owning our own software stack, hippo.com has refined its services over the years to provide good coverage not only of the easier B2B domains but also the more technically tricky B2C domains including: Hotmail Yahoo AOL Yandex 7

12 3.1.5 Unrivalled Integration RESTful endpoints integrate with pretty much anything these days. hippo.com not only supports server to server integration over REST but server to client integration with full support for CORS. CORS is available in most modern web browsers and allows rich, client side development using only HTML and JavaScript (jquery or AngularJS recommended). See Integration for tested integration examples using a wide range of languages including PHP, Java,.NET, jquery and AngularJS) Spam Trap Detection After many years R&D, hippo.com has developed various secret sauces that can effectively detect and eliminate spam traps from several well known Block List Disposable Address Detection Detect and eliminate DEA Unrivalled Performance Strategic data centers in North America and Europe, aggressive caching and cloud based auto-scaling deliver outstanding performance. Typical queries are answered between 0.2 to 1.5 seconds. Note: See Technical Specification API Based Verification Every plan includes authentication systems based on ACL and License Key based access. Domain based ACL authentication is typically used for client script integrations (e.g. jquery or AngularJS). Domain licenses are tied into a single domain (e.g. License Key based authentication is typically used for server to server integrations Error Correction No more fat finger syndrome! Our API has an optional feature to remove certain invalid characters such as spaces, slashes etc Common Typo Handling hippo.com also searches for common typos and suggest alternatives. E.g. [email protected] is more likely to be [email protected] so hippo.com will validate what the user has entered, but provide you with the more likely alternative suggestion too. 8 Chapter 3. Features

13 On Screen Reporting Every account comes with a secure online portal for customers to view their current and historic usage via simple, user friendly donut charts Thoughtful Versioning Endpoints are versioned. This means that hippo.com can continue to release new functionality without breaking existing clients committed to integrating with our systems on legacy endpoints What it does hippo.com is used to check addresses in real-time. Not only are syntax and domain checked, but that the user mailbox is available too. This is the only way to know for sure if an address is valid. Additionally identified as part of the verification process is extra information including: DEA. Spam Trap How it works addresses are verified using various filters and processes. As a high level overview, an address submitted for verification goes thorough the following filters: Syntax A basic inspection of the syntax of the address to see if it looks valid. Work is done only using server CPU (Central Processing Unit) based on simple pattern matching algorithms. DNS A Verifies a domain exists in DNS. Domains that do not exist in DNS cannot have mail servers or boxes. DNS checks are performed over the network. DNS MX Verify MX records using DNS. Domains that do not have MX records, have no mail servers and therefore no valid boxes. MX checks are performed over the network. MailBox Verify boxes with SMTP checks. Connect to mail server and perform SMTP protocol to verify if mail box exists. This is the deepest level of verification. It is performed over the network Features 9

14 10 Chapter 3. Features

15 CHAPTER 4 Technical Specification 4.1 Technical Specification Infrastructure Manufacturer hippo.com Uptime > 99.9% Response time >0.2seconds < 8 seconds. Typical response time 0.7 seconds. Throughput and concurrency > 100 TPS (Transactions Per Second) Integration RESTful GET over HTTP(S) Authentication Key or Domain based ACL (Access Control List) Infrastructure Geographically dispersed data centers, auto load balance / failover Application Syntax checking? DNS A checking? DNS MX checking Mailbox checking Reporting / charts? Versioning supported? B2B (Business to Business) coverage? Hotmail coverage? Yahoo coverage? AOL coverage? Yandex coverage? Secure? Spam trap detection? Illegal character detection Typo detection DEA (Disposable Address) detection? Reporting charts Server to browser client supported? Server to server supported? CORS (Cross-Origin Resource Sharing)? yes yes yes yes yes yes yes yes yes yes yes yes. HTTPS supported. partial yes yes yes yes yes yes yes 11

16 12 Chapter 4. Technical Specification

17 CHAPTER 5 Installation 5.1 Installation There is no software to install. hippo is Software as a Service exposed as a simple RESTful service that is available to anything connected to The Internet. 13

18 14 Chapter 5. Installation

19 CHAPTER 6 Configuration And Usage 6.1 Configuration And Usage Authentication Each call to the API must be authenticated. Authentication with the API is performed by either: ACL. License Key Accessing the API using key authentication Access the API at: Sending the following parameters :- Figure 1 - REST Request Variables Parameter Value key your unique API key supplied by us required the address to be validated required correct 1 - this will remove certain invalid characters. 0 - this will leave the untouched. optional Note: Need a license key? Click here Accessing the API using ACL authentication 15

20 Note: For ACL based authentication, it is not necessary to include the license key in the request. Other parameters (e.g. correct ) are supported as in the key based example as in Figure 1 - REST Request Variables Responses Note: For a full definition of possible responses, see Verification Response Codes For API V1. You will receive back the following values in the response. Figure 2 - Responses Response Description Example values status The validation result Ok, Bad, Unknown additionalstatus Additional information for BAD and UNKNOWN results NoMxServers- Found addressprovided The exact address passed to the API including obvious typos and [email protected] errors address- The actual address validated [email protected] Checked addresssuggestion A suggested alternative if a common typo was noticed e.g. if [email protected] was provided Note: Example response for address [email protected] [email protected] The URL passed to the API is :- The response would be :- { "status":"bad", "additionalstatus":"mailboxdoesnotexist", " addressprovided":"[email protected]", " addresschecked":"[email protected]", " addresssuggestion":"" The correct Parameter Optionally, you can also use the correct parameter to remove certain invalid characters such as spaces, slashes, square brackets etc. Example using the correct parameter. The user enters an address john99]@gmail.com Here is the API call that would be made :- hippo.com will automatically remove the invalid character ] and send the corrected version through for validation. Example results based on the above API call :- 16 Chapter 6. Configuration And Usage

21 { "status":"ok", "additionalstatus":"none", " addresssuggestion":"" Additional Status Information When an address is returned with a status of Bad or Unknown we return the detailed reason as part of the response in the additionalstatus value. For a full list of additional status values, please refer to Verification Response Codes For API V Sandbox A sandbox environment is available to assist customers with testing, evaluation and integration. The sandbox url is: There is no charge for use and your live quota is not affected. No s are verified in the sandbox and responses are hard coded. For a full list of hard coded test cases, please see here Firewall If you need to enable firewall rules based on IP addresses, you will need to add the following addresses, for ports 80 and 443, to y Configuration And Usage 17

22 18 Chapter 6. Configuration And Usage

23 CHAPTER 7 Integration 7.1 Integration See comprehensive Integration Examples showing diverse examples of server and client languages. 19

24 20 Chapter 7. Integration

25 CHAPTER 8 Plugins 8.1 Plug-ins jquery Validation Plug-in jquery Plugin is a generic jquery library has been constructed to use RESTful verification services from Grab the jquery-plugin over at GitHub. 21

26 22 Chapter 8. Plugins

27 CHAPTER 9 FAQs 9.1 Frequently Asked Questions How can I get a key? Click here to request a license key How do I call the API? Make a simple GET request to the endpoint. For example, to query address [email protected] with license key ABCD1234 call: What comes back from the API? A JSON based response similar to: { "status":"bad", "additionalstatus":"mailboxdoesnotexist", " addressprovided":"[email protected]", " addresschecked":"[email protected]", " addresssuggestion":"" Note: For a detailed explanation of response codes, please see Verification Response Codes For API V How can I integrate the API with my solution? We have tested, detailed integration examples using a wide range of technologies and languages including Java, PHP,.NET, jquery and Angular. Please see Integration for more information. 23

28 9.1.5 How reliable is the API? > 99.9% average availability Does the system get slower when it s busy? No. All infrastructure is hosted in cloud based platforms with automatic scaling enabled. Automatic scaling kicks in at busy times to provide more hardware resources to meet demand Can it do Hotmail? Yes Can it do Yahoo? Yes. Based on our own internal testing hippo.com is currently the only verification service to offer effective and repeatable coverage for Yahoo addresses Can it do Yandex? Yes it can Can it find spam traps? Partially. A Spam Trap is a moving target. In theory (and indeed in practice) anyone can setup a Block List and start putting spam traps into the wild. hippo.com has Spam Trap detection capabilities that covers several of the well known block lists. Whilst it is not possible to deliver 100% coverage of all spam traps from all block lists, hippo.com provides the best Spam Trap detection capabilities available How does it work? At a basic conceptual level, the process of verifying addresses is very simple. Google for Send using telnet for a quick and general overview of how it s done. To verify an address without sending an , simply go as far as the RCPT TO stage and parse the response code. That s the easy bit and can be accomplished in just a couple of dozen lines of a PHP script! The hard bit is dealing with mail services that are intrinsically configured to work against the process of verification or any similar SMTP based activity. The reason that any / SMTP process is difficult from a client perspective is that mail services need to protect themselves from an ever increasing landscape of abuse including spam and DDoS attacks. hippo.com s strength in dealing with the hard bit of verification comes from years of experience in doing verification together with our complete ownership of our SMTP verification software stack together with an extensive cloud based infrastructure. That s why hippo.com can do the hard bits best and offer outstanding coverage on the more difficult domains such as Yahoo and Hotmail. 24 Chapter 9. FAQs

29 Can I get blacklisted using this API? No. It s hippo.com infrastructure that does the work Will anyone know that I am verifying their address? No. It s hippo.com infrastructure that does the work Your service says an address is OK and I know it s Bad (or vice versa)? hippo.com queries mail servers in real time. Mail servers respond with one of 2 possible answers for a given address: Yes, the address exists - SMTP code 2xx No, the address doe not exist - SMTP code 5xx hippo.com uses the above response codes to determine if an address is valid or not and reports this back to you. This method of determining address validity works in >99% cases. However, nothing is guaranteed. In a small number of cases it is possible for a mail server to report one thing on verification and do something different on trying to deliver an to the address verified. At the time of verification the mail server would have reported Yes/No, however this may have been due to an error within the target mail server and the opposite may have been true. This is rare, but it can happen. If this was a temporary error within the target mail server, please note that this result may be remembered by our system for a few hours. For another example, say we take an address of [email protected] to send to. We are sending from a fictitious address [email protected]. [email protected] reports with status code of OK from the verification API. However, when you send an to [email protected], the bounces. Further inspection of the bounced Non Delivery Report (NDR) headers show something like the following: Delivered-To: [email protected] Received: by with SMTP id n6csp24867ioo; Sat, 6 Jun :57: (PST) X-Received: by with SMTP id 5mr oie ; Sat, 06 Jun :57: (PST) Return-Path: <> Received: from SNT004-OMC2S34.hotmail.com (snt004-omc2s34.hotmail.com. [ ]) by mx.google.com with ESMTPS id ws5si obb for <[email protected]> (version=tlsv1.2 cipher=ecdhe-rsa-aes128-sha bits=128/128); Fri, 6 Jun :57: (PST) Received-SPF: none (google.com: SNT004-OMC2S34.hotmail.com does not designate permitted sender hosts) Authentication-Results: mx.google.com; spf=none (google.com: SNT004-OMC2S34.hotmail.com does not designate permitted sender hosts Received: from SNT004-MC2F40.hotmail.com ([ ]) by SNT004-OMC2S34.hotmail.com over TLS secur Fri, 6 Jun :57: From: [email protected] To: [email protected] Date: Fri, 6 Jun :57: MIME-Version: 1.0 Content-Type: multipart/report; report-type=delivery-status; boundary="9b095b5adsn=_01d010aabce2c5cc0008c930snt004?mc2f40.ho" 9.1. Frequently Asked Questions 25

30 X-DSNContext: 335a7efd Message-ID: <mjz7zgtpi @snt004-mc2f40.hotmail.com> Subject: Delivery Status Notification (Failure) Return-Path: <> X-OriginalArrivalTime: 06 Jun :57: (UTC) FILETIME=[CEAD2EE0:01D0114B] This is a MIME-formatted message. Portions of this message may be unreadable without a MIME-capable mail program. --9B095B5ADSN=_01D010AABCE2C5CC0008C930SNT004?MC2F40.ho Content-Type: text/plain; charset=unicode-1-1-utf-7 This is an automatically generated Delivery Status Notification. Delivery to the following recipients failed. [email protected] The header of the NDR shows that Hotmail thinks the address is invalid as far as sending to this address is concerned. However, Hotmail reports that the same address is valid as far as the verification activity performed by hippo.com. The discrepancy in verification results versus mail send is with the Hotmail infrastructure reporting one thing but doing the exact opposite. This behaviour occasionally (particularly from Hotmail) is seen in a small amount of cases and is attributable to internal Hotmail (or other mail services) system anomalies. The majority (>99%) of verification status versus mail send is consistent. However there are some edge cases caused by system faults in the mail service providers themselves. For these small number of cases, there is nothing that can be done at the verification stage. 26 Chapter 9. FAQs

31 CHAPTER 10 Status Codes Verification Response Codes For API V1 A response is a message consisting of a standard HTTP header and body. The body of the message contains the detail of the message (e.g. the JSON data with verification detail). The header of the message contains general HTTP information such as HTTP status codes. Response Body Content Main Status Response Codes Additional Status Codes Response Header HTTP Status Codes Response Body Content Main Status Response Codes Ok Verification passes all checks including Syntax, DNS, MX, Mailbox, Deep Server Configuration, Grey Listing Bad Verification fails checks for definitive reasons (e.g. mail box does not exist) Unknown Conclusive verification result cannot be achieved due to mail server configuration or anti-spam measures. See table Additional Status Codes. Additional Status Codes None No additional information is available. This status differs from a TransientNetworkFault as it should not be retried (the result will not change). There are a few known reasons for this status code for example the target mx record uses Office 365 or a mail provider implementing custom mailbox shutdowns. AtSignNotFound The sign is not found in address. 27

32 DomainIsInexistent The domain (i.e. the bit after character) defined in the address does not exist, according to DNS records. A domain that does not exist cannot have boxes. A domain that does not exist cannot have boxes. DomainIsWellKnownDea The domain is a well known Disposable Address DEA. There are many services available that permit users to use a one-time only address. Typically, these addresses are used by individuals wishing to gain access to content or services requiring registration of addresses but same individuals not wishing to divulge their true identities (e.g. permanent addresses). DEA addresses should not be regarded as valid for send purposes as it is unlikely that messages sent to DEA addresses will ever be read. MailboxFull The mailbox is full. Mailboxes that are full are unable to receive any further messages until such time as the user empties the mail box or the system administrator grants extra storage quota. Most full mailboxes usually indicate accounts that have been abandoned by users and will therefore never be looked at again. We do not recommend sending s to addresses identified as full. MailboxDoesNotExist The mailbox does not exist. 100% confidence that the mail box does not exist. NoMxServersFound There are no mail servers defined for this domain, according to DNS. addresses cannot be valid if there are no servers defined in DNS for the domain. ServerDoesNotSupportInternationalMailboxes The server does not support international mailboxes. International boxes are those that use international character sets such as Chinese / Kanji etc. International boxes require systems in place for Punycode translation. Where these systems are not in place, verification or delivery is not possible. For further information see Punycode. ServerIsCatchAll The server is configured for catch all and responds to all verifications with a status of Ok. Mail servers can be configured with a policy known as Catch All. Catch all redirects any address sent to a particular domain to a central box for manual inspection. Catch all configured servers cannot respond to requests for address verification. Success Successful verification. 100% confidence that the mail box exists. TooManyAtSignsFound Too signs found in address. Only character is allowed in addresses. Unknown The reason for the verification result is unknown. TransientNetworkFault A temporary network fault occurred during verification. Please try again later. Verification operations on remote mail servers can sometimes fail for a number of reasons such as loss of network connection, remote servers timing out etc. One other possible cause of a temporary fault is Grey Listing. 28 Chapter 10. Status Codes

33 These conditions are usually temporary. Retrying verification at a later time will usually result in a positive response from mail servers. Please note that setting an infinite retry policy around this status code is inadvisable as there is no way of knowing when the issue will be resolved within the target domain or the grey listing resolved, and this may affect your daily quota. PossibleSpamTrapDetected A possible spam trap address or domain has been detected. Spam traps are addresses or domains deliberately placed on-line in order to capture and flag potential spam based operations. Our advanced detection heuristics are capable of detecting likely spam trap addresses or domains known to be associated with spam trap techniques. We do not recommend sending s to addresses identified as associated with known spam trap behaviour. Sending s to known spam traps or domains will result in your ESP being subjected to blocks from a DNS Block List.. An ESP cannot tolerate entries in a Block List (as it adversely affects deliver-ability for all customers) and will actively refuse to send s on behalf of customers with a history of generating entries in a Block List Response Header HTTP Status Codes In additional to the application level codes (see Main Status Response Codes and Additional Status Codes) returned in the HTTP message body, HTTP status codes are returned in the HTTP header. 200 Call successful. 304 The cached copy on the client is up to date. Resource not transferred. Use this with client side If-Modified-Since request for efficient caching. Caching is available for both HTTP and HTTPS options. 400 Bad request. The server could not understand the request. Perhaps missing a license key or an to check? Conditions that lead to this error are: No license key supplied, no address supplied, address > 255 characters, license key in incorrect format. 401 Possible reasons: The provided license key is not valid, the provided license key has expired, the provided license key is not permitted for use from this domain, you have reached your quota capacity for this account, this account has been disabled. 500 An error occurred on the server. Possible reasons are: license key validation failed or a general server fault Verification Response Codes For API V1 29

34 30 Chapter 10. Status Codes

35 CHAPTER 11 Integration Examples 11.1 Integration Examples Server Examples PHP <?php // URL which should be requested $url = ' $apikey = 'YOUR API KEY'; // API Key $ = ' Address to Test'; // to test // json String for request $url.= "? =$ &key=$apikey"; // Initializing curl $ch = curl_init( $url ); if($ch == false) { die ("Curl failed!"); else { // Configuring curl options $options = array( CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => array('content-type: application/json') ); // Setting curl options curl_setopt_array( $ch, $options ); // Getting results $result = curl_exec($ch); // Getting json result string // display JSON data 31

36 echo "$result";?> C# #region Usings using System; using System.IO; using System.Net; #endregion /// <summary> /// The program. /// </summary> internal class Program { #region Constants /// <summary> /// The api url. /// </summary> private const string ApiUrl /// <summary> /// 0 = ApiUrl /// 1 = address to query /// 2 = API Key /// </summary> private const string QueryFormatString /// <summary> /// The your api key. /// </summary> /// <remarks> /// /ENTER YOUR API KEY HERE/ /// </remarks> private const string YourAPIKey ENTER A VALID KEY HERE-->"; #endregion #region Methods /// <summary> /// The main program entry point. /// </summary> /// <param name="args"> /// The args. /// </param> private static void Main(string[] args) { Console.WriteLine("Input address to verify"); var readline = Console.ReadLine(); 32 Chapter 11. Integration Examples

37 Console.WriteLine(string.Empty); var requesturl = string.format(queryformatstring, ApiUrl, readline, YourAPIKey); var myrequest = (HttpWebRequest)WebRequest.Create(requestUrl); WebResponse webresponse = null; try { webresponse = myrequest.getresponse(); using (var reader = new StreamReader(webResponse.GetResponseStream())) { var jsonstring = reader.readtoend(); Console.ForegroundColor = ConsoleColor.Green; Console.WriteLine("Result:"); Console.WriteLine(jsonString); Console.ResetColor(); Console.WriteLine("Press <Enter> to continue.."); Console.ReadLine(); catch (Exception exception) { Console.WriteLine("An error occured:"); Console.ForegroundColor = ConsoleColor.Red; Console.WriteLine("Exception reported: {0", exception.message); Console.ResetColor(); Console.WriteLine("Press <Enter> to continue.."); Console.ReadLine(); finally { if (webresponse!= null) { webresponse.dispose(); #endregion VB.net Imports System.IO Imports System.Net ''' <summary> ''' The program. ''' </summary> Friend Class Program #Region "Constants" Integration Examples 33

38 ''' <summary> ''' The api url. ''' </summary> Private Const ApiUrl As String = " ''' <summary> ''' 0 = ApiUrl ''' 1 = address to query ''' 2 = API Key ''' </summary> Private Const QueryFormatString As String = "{0? ={1&key={2" ''' <summary> ''' The your api key. ''' </summary> ''' <remarks> ''' /ENTER YOUR API KEY HERE/ ''' </remarks> Private Const YourAPIKey As String = "<!-- ENTER A VALID KEY HERE-->" #End Region #Region "Methods" ''' <summary> ''' The main program entry point. ''' </summary> ''' <param name="args"> ''' The args. ''' </param> Private Shared Sub Main(args As String()) Console.WriteLine("Input address to verify") Dim readline = Console.ReadLine() Console.WriteLine(String.Empty) Dim requesturl = String.Format(QueryFormatString, ApiUrl, readline, YourAPIKey) Dim myrequest = DirectCast(WebRequest.Create(requestUrl), HttpWebRequest) Dim webresponse As WebResponse = Nothing Try webresponse = myrequest.getresponse() Using reader = New StreamReader(webResponse.GetResponseStream()) Dim jsonstring = reader.readtoend() Console.ForegroundColor = ConsoleColor.Green Console.WriteLine("Result:") Console.WriteLine(jsonString) Console.ResetColor() Console.WriteLine("Press <Enter> to continue..") Console.ReadLine() End Using Catch exception As Exception 34 Chapter 11. Integration Examples

39 End Sub Finally End Try Console.WriteLine("An error occured:") Console.ForegroundColor = ConsoleColor.Red Console.WriteLine("Exception reported: {0", exception.message) Console.ResetColor() Console.WriteLine("Press <Enter> to continue..") Console.ReadLine() If webresponse IsNot Nothing Then webresponse.dispose() End If #End Region End Class Java / Company: (c) 2016, -checker.com ( File name: java.v1_key_acl Version: Version control: initial release Date: August 2014 Description: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using java. This example requires a valid key to work correctly. License: Apache 2.0 ( / import java.io.bufferedreader; import java.io.ioexception; import java.io.inputstreamreader; import java.net.httpurlconnection; import java.net.url; import java.util.scanner; import java.util.logging.level; import java.util.logging.logger; public class Program { Integration Examples 35

40 / The URL which should be requested / private static final String ApiUrl = " / Query string for request %1$s = ApiUrl %2$s = address to query %3$s = API Key / private static final String QueryFormatString = "%1$s? =%2$s&key=%3$s"; / Your API Key / private static final String YourAPIKey = "/ ENTER A VALID KEY HERE /"; / The main program entry args the command line IOException If the server does not return a success response / public static void main(string[] args) { System.out.println("Input address to verify"); // Create a scanner to read in the requested address Scanner in = new Scanner(System.in); String readline = in.next(); try { // Format the request url to the correct structure for the request URL requesturl = new URL(String.format(QueryFormatString, ApiUrl, readline, Y // Open a connection to the website HttpURLConnection myrequest = (HttpURLConnection) requesturl.openconnection( // Set the type to HTTP GET myrequest.setrequestmethod("get"); // Create a new buffered reader to read the response back from the server BufferedReader reader = new BufferedReader( new InputStreamReader(myRequest.getInputStream())); String inputline; StringBuilder response = new StringBuilder(); // Read in the response line from the server while ((inputline = reader.readline())!=null ) { response.append(inputline); // Close the reader reader.close(); 36 Chapter 11. Integration Examples

41 // Output the result to console System.out.println(response.toString()); catch (IOException ex) { Logger.getLogger(Program.class.getName()).log(Level.SEVERE, null, ex); Python ########################################################################################### # Company: # (c) 2016, hippo.com ( # # Version: # # # Version control: # initial release # # Date: # August 2014 # # Description: # Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 # using Python # # This example requires a valid key to work correctly. # # License: # Apache 2.0 ( ########################################################################################### # Import the module for handling the http request import urllib.request # The url for the service ApiUrl = " # The format of the full query string QueryFormatString = "{0? ={1&key={2" # The API key provided for your account goes here YourAPIKey = "<!-- ENTER A VALID KEY HERE-->" # Read in the user input readline = input("enter \n") # Format the full url and make the http GET request and read the response response = urllib.request.urlopen(queryformatstring.format(apiurl, readline, YourAPIKey)).read() # Print the response print(response) Integration Examples 37

42 PERL ########################################################################################### # Company: # (c) 2016, hippo.com ( # # File name: # Program.pl # # Version: # # # Version control: # initial release # # Date: # August 2014 # # Description: # Demonstrates how to call a RESTful //api.27hub.com/api/a/v1 # using Perl using client side only calls. # # This example requires a valid key to work correctly. # # License: # Apache 2.0 ( ########################################################################################### use LWP; # The url for the service $ApiUrl = " # The format of the full query string $QueryFormatString = "%s? =%s&key=%s"; print "Enter \n"; $readline = <STDIN>; # The API key provided for your account goes here $YourAPIKey = "<!-- ENTER A VALID KEY HERE-->"; # Format the url request $requesturl = sprintf $QueryFormatString, $ApiUrl, $readline, $YourAPIKey; # Make the request against the REST service $browser = LWP::UserAgent->new; $response = $browser->get($requesturl); # Print the response print $response->content; Client Examples jquery (domain ACL) 38 Chapter 11. Integration Examples

43 Note: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using jquery, client side only calls. <!DOCTYPE html> <!-- Company: (c) 2016, hippo.com ( File name: v1_domain_acl.html Version: Version control: initial release Date: August 2014 Description: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using jquery, client side only calls. This example requires a domain ACL and hosting at specified domain to work correctly. License: Apache 2.0 ( --> <html lang="en" xmlns=" <head> <meta charset="utf-8" /> <title> hippo.com : Domain Access Control List Sample.</title> <style type="text/css">.statusunknown{ color: #c1c72c;.statusok{ color: #009933;.statusBad,.errorMsg{ color: #ff0000; input[type='text']{ width: 300px; p label {display: inline-block; width: 60px; </style> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> </head> <body> <h1> hippo.com : verification demo using domain access control list aut <h2>about</h2> <p>this example shows how to perform verification using just client side sc <h2>how to run this sample</h2> <p>two things are needed to run this sample:</p> <ol> <li>a domain <abbr title="access Control List">ACL</abbr> is required fro <li>web hosting for </ol> <p>please upload this sample to your web host in order to run.</p> <h2>key features</h2> <ul> Integration Examples 39

44 <li>compatible with all modern browsers</li> <li>uses jquery </li> <li>no server side scripting required</li> </ul> <hr/> <h2>try it</h2> <p> <label for=" "> </label> <input type="text" name=" " id=" " /> <input type="button" name="submit" id="submit" value="verify"/> </p> <div id="validationresult"></div> <!--Result output here--> <script> /nest key logic inside document.ready to ensure functionality only avail $(function () { console.log("ready!"); $('#submit').click(function () { var text = $('# ').val(); if ( text.length == 0) { $('#validationresult').html("<span class='errorms return; $('#validationresult').html("verifying..."); var verifyapi = '//api1.27hub.com/api/a/v1? =' + ); ); /execute remote request to perform verification. A $.getjson( verifyapi, {).done(function (data) { reportresult(data); ).fail(function (jqxhr, textstatus, error) { var err = textstatus + ", " + error; console.log("request failed: " + err); );; /Output result to the 'validationresult' div element/ function reportresult(data) { var status = data['status'].tolowercase(); // get 'status' from R var additionalstatus = data['additionalstatus']; // get 'addition var message = data['message']; // if there is an error (e.g. lice console.log(status); console.log(additionalstatus); console.log(message); var statushtml; // if there is an error message, show here if (message!= null && message!= '') { statushtml = "<span class='errormsg'>error. Message='" + else { 40 Chapter 11. Integration Examples

45 // map REST response data to presentation messages. switch (status) { case 'ok': statushtml = "<span class='statusok'>emai break; case 'bad': statushtml = "<span class='statusbad'>ema break; default: statushtml = "<span class='statusunknown' break; </html> </body> </script> console.log(statushtml); // present the result on screen $('#validationresult').html(statushtml); jquery (license key) Note: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using jquery using client side only calls <!DOCTYPE html> <!-- Company: (c) 2016, ( File name: v1_key_acl.html Version: Version control: initial release Date: August 2014 Description: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using jquery using client side only calls. This example requires a valid key to work correctly. License: Apache 2.0 ( Integration Examples 41

46 --> <html lang="en" xmlns=" <head> <meta charset="utf-8" /> <title>27hub.com : License Key Sample.</title> <style type="text/css">.statusunknown { color: #c1c72c; </head> <body>.statusok { color: #009933;.statusBad,.errorMsg { color: #ff0000; input[type='text'] { width: 300px; p label { display: inline-block; width: 60px; </style> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> <h1>27hub.com : verification demo using simple key authentication with jquery.</h1> <h2>about</h2> <p>this example shows how to perform verification using just client side scripting <h2>how to run this sample</h2> <p>this page can be hosted anywhere (i.e. any web host or platform). The only thing neede <h2>key features</h2> <ul> <li>compatible with all modern browsers</li> <li>uses jquery </li> <li>no server side scripting required</li> </ul> <hr /> <h2>try it</h2> <p> <label for="key">key:</label> <input type="text" id="key" name="key" tabindex="1" maxlength="20" /> </p> <p> <label for=" "> </label> <input type="text" name=" " id=" " tabindex="2" /> <input type="button" name="submit" id="submit" tabindex="3" value="verify" /> </p> <div id="validationresult"></div> <!--Result output here--> <script> /nest key logic inside document.ready to ensure functionality only avail $(function () { console.log("ready!"); $('#submit').click(function () { 42 Chapter 11. Integration Examples

47 var text = $('# ').val(); // get key from text b var keytext = $('#key').val(); // get address to be if (keytext.length == 0) { $('#validationresult').html("<span class='errorms return; if ( text.length == 0) { $('#validationresult').html("<span class='errorms return; $('#validationresult').html("verifying..."); var 27hub = '//api1.27hub.com/api/a/v1? =' + encodeur ); ); /execute remote request to perform verification. A $.getjson(27hub, {).done(function (data) { reportresult(data); ).fail(function (jqxhr, textstatus, error) { var err = textstatus + ", " + error; console.log("request failed: " + err); );; /Output result to the 'validationresult' div element/ function reportresult(data) { var status = data['status'].tolowercase(); // get 'status' from R var additionalstatus = data['additionalstatus']; // get 'addition var message = data['message']; // if there is an error (e.g. lice console.log(status); console.log(additionalstatus); console.log(message); var statushtml; // if there is an error message, show here if (message!= null && message!= '') { statushtml = "<span class='errormsg'>error. Message='" + else { // map REST response data to presentation messages. switch (status) { case 'ok': statushtml = "<span class='statusok'>emai break; case 'bad': statushtml = "<span class='statusbad'>ema break; default: statushtml = "<span class='statusunknown' break; Integration Examples 43

48 console.log(statushtml); </body> </html> </script> // present the result on screen $('#validationresult').html(statushtml); AngularJS (license key) Note: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using AngularJS with client side only calls. <!DOCTYPE html> <!-- Company: (c) 2016, hippo.com ( File name: v1_key_acl.html Version: Version control: initial release Date: August 2014 Description: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using AngularJS with client side only calls. This example requires a valid key to work correctly. License: Apache 2.0 ( --> <html lang="en" xmlns=" <head> <meta charset="utf-8" /> <title> hippo.com : License Key Sample.</title> <style type="text/css">.statusunknown { color: #c1c72c;.statusok { 44 Chapter 11. Integration Examples

49 color: #009933;.statusBad,.errorMsg { color: #ff0000; input[type='text'],input[type=' '] { width: 300px; p label { display: inline-block; width: 60px; </style> </head> <body> <h1> hippo.com : verification demo using simple key authentication with Angular <h2>about</h2> <p>this example shows how to perform verification using just client side scripting <h2>how to run this sample</h2> <p>this page can be hosted anywhere (i.e. any web host or platform). The only thing neede <h2>key features</h2> <ul> <li>compatible with all modern browsers</li> <li>uses AngularJS </li> <li>no server side scripting required</li> </ul> <hr /> <h2>try it</h2> <div id="myapp" ng-app="apidemo" ng-controller="apidemocontroller"> <form name="verifyform" novalidate="" ng-submit="doverify()"> <p> <label for="key">key:</label> <input type="text" id="key" name="key" tabindex="1" maxlength="20 <span class="errormsg" ng-show="verifyform.key.$error.required"> </p> <p> <label for=" "> </label> <input type=" " name=" " id=" " tabindex="2" ng-model <span class="errormsg" ng-show="verifyform. .$error.required" <span class="errormsg" ng-show="verifyform. .$error. ">no </p> <p> <label> </label> <input type="submit" name="submit" id="submit" tabindex="3" value </p> </form> <div id="validationresult"><!--result output here--> <div ng-show="showvalidating">verifying..</div> <div ng-show="showok"><span class="statusok"> address is ok.</span>< <div ng-show="showbad"><span class="statusbad"> address is not valid <div ng-show="showunknown"><span class="statusunknown">unable to validate <div ng-show="showmessage"><span class="errormsg">error. Message={{errorM </div> </div> <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.2.23/angular.min.js"></script> Integration Examples 45

50 <script> // Module var app = angular.module('apidemo', []); // Controller app.controller('apidemocontroller', function apidemocontroller($scope,$http) { $scope.query = { key: "", "" ; $scope.result = { status: "", additionalstatus: "" ; // verification event $scope.doverify = function () { resetmessage(); $scope.showvalidating = true; var verifyapi = '//api1.27hub.com/api/a/v1? =' + encodeu console.log( verifyapi); $http.get( verifyapi).success(function (response) { resetmessage(); var status = response['status'].tolowercase(); var additionalstatus = response['additionalstatus var message = response['message']; console.log(status); console.log(additionalstatus); console.log(message); // if there is an error message, show here if (message!= null && message!= '') { $scope.errormessage = message; $scope.showmessage = true; else { // map REST response data to presentation switch (status) { case 'ok': $scope.showok = true; break; case 'bad': $scope.showbad = true; break; default: $scope.additionalstatusme $scope.showunknown = true ); break; 46 Chapter 11. Integration Examples

51 ); // function resetmessage() { $scope.showvalidating = false; $scope.showbad = false; $scope.showmessage = false; $scope.showok = false; $scope.showunknown = false; $scope.showmessage = false; </script> </body> </html> CURL Company: 2016, hippo.com ( File name: curl.txt Version: Version control: initial release Date: August 2014 Description: Demonstrates how to call a RESTful //api1.27hub.com/api/a/v1 using curl This example requires a valid key to work correctly. License: Apache 2.0 ( curl -i -H "Accept: application/json" " Integration Examples 47

52 48 Chapter 11. Integration Examples

53 CHAPTER 12 Glossary 12.1 Glossary ACL Access Control List. An ACL is checked against the domain calling the API. ACL authentication does not require a license key and is best in situations where the API is being called from client side script such as JavaScript, jquery, Angular etc. API Application Programmers Interface. See Wikipedia - API Definition for more information. B2B Business To(2) Business Business hosting services are generally private, enterprise grade hosting services typically hosted in either private data centers or in cloud based infrastructure such. Business to business refers to the activity of businesses sending to clients using business addresses. B2C Business To(2) Consumer Consumer hosting providers are generally well known, mostly web based providers such as Hotmail, Yahoo, AOL, Gmail etc. Business to consumer refers to the activity of businesses sending to clients using consumer addresses. Verifying addresses in consumer domains is generally more technically challenging than B2B Block List See DNSBL. CORS Cross Origin Resource Scripting Allows modern browsers to work with script (e.g. JavaScript) and JSON data originating form other domains. CORS is required to allow client script such a JavaScript, jquery or AngularJS to work with results returned from an external RESTful API. See Wikipedia - CORS for more information. DDoS Distributed Denial of Service See Wikipedia - Denial-of-service attack for more information. DEA Disposable Address There are many services available that permit users to use a one-time only address. Typically, these addresses are used by individuals wishing to gain access to content or services requiring registration of addresses but same individuals not wishing to divulge their true identities (e.g. permanent addresses). 49

54 DEA addresses should not be regarded as valid for send purposes as it is unlikely that messages sent to DEA addresses will ever be read. DEA addresses should not be regarded as valid for send purposes as it is unlikely that messages sent to DEA addresses will ever be read. DNS Domain Name System At its simplest level, DNS converts text based queries (e.g. a domain name) into IP addresses. DNS is also responsible for providing the MX records needed to locate a domains mail servers. See Wikipedia - Domain Name System for more information. DNSBL DNS Block List As an anti-spam measure, mail servers can use spam black lists to look up the reputation of IP addresses and domains sending . If an IP or domain is on a block list, the mail server may reject the senders message. See Wikipedia - DNSBL for more information. ESP Service Provider A service that sends s on your behalf. See Wikipedia - service provider (marketing) for more information. Grey Listing A technique used in mail servers as an anti-spam technique. Sometimes also known as deferred, grey listing arbitrarily delays the delivery of s with a try again later response to the client sending the . See Wikipedia - Grey Listing for more information. HTTP Hypertext Transfer Protocol See Wikipedia - Hypertext Transfer Protocol for more information. JSON JavaScript Object Notation JavaScript Object Notation, is an open standard format that uses human readable text to transmit data objects consisting of attribute value pairs. It is used primarily to transmit data between a server and web application, as an efficient, modern alternative to XML. See Wikipedia - JSON for more information. License Key License key authentication is best for situations where simplicity is required and you can keep the key private. An ideal use case for key authentication would be for server based applications calling the RESTful API. MX Click here to request a license key. Mail Exchanger The MX is a server responsible for interchange with a client. Office 365 Office 365 mail servers (e.g. x-com.mail.protection.outlook.com) are always configured with the catch all policy, accepting all s sent to the domain and redirecting them to a central box for manual inspection. Catch all configured servers cannot respond to requests for address verification. This does not affect our coverage of Hotmail, Live and Outlook mail boxes. Punycode Punycode is a way to represent Unicode with the limited character subset of ASCII supported by the Domain Name System. See Wikipedia - Punycode for more information. RESTful Representational state transfer See Wikipedia - RESTful for further information. 50 Chapter 12. Glossary

55 SMTP Simple Mail Transport Protocol SMTP is a protocol. It is the sequence of commands and responses between a client (the software sending an ) and server (the software receiving an ) that facilitates the sending and receiving of between computer based messaging systems. Spam Trap Spam traps are addresses used for the sole purpose of detecting spamming activities. Spam traps are used by many block lists (DNSBL) to detect spammers. For more information, see Wikipedia - Spam Traps Glossary 51

56 52 Chapter 12. Glossary

57 Index A ACL, 49 API, 49 B B2B, 49 B2C, 49 Block List, 49 C CORS, 49 D DDoS, 49 DEA, 49 DNS, 50 DNSBL, 50 E ESP, 50 G Grey Listing, 50 H HTTP, 50 J JSON, 50 L License Key, 50 M MX, 50 O Office 365, 50 P Punycode, 50 R RESTful, 50 S SMTP, 51 Spam Trap, 51 53