Email Validation Integration Guide
This guide explains how to access GBGroup's Email Validation web service product using their Identity Management Platform (IdM), available via SOAP web services.
The fundamentals of integrating with the service are described here: Integration Fundamentals
Service Description
The email validation service provides full validation of an email address via the following stages:
1. Checks that the provided Email Address conforms to the valid syntax required for an email address
2. Validates Domain and runs a DNS check, recognising common mispellings and return a suggested spelling if necessary
3. Real-time checks to assess the validity of the domain, whether the catch-all domain is specified and whether the email is deliverable.
For further advice on how to approach email validation head to Understanding Email Validation
Input Criteria
Method: ExecuteCapture
The ExecuteCapture method is used to access the Email Validation product and services by specifying the corresponding profile.
Input Details
Type: ExecuteCaptureRequest
| Field Name | Type | Description |
|---|---|---|
| securityHeader | SecurityHeader | The username used to access the system including domain name (e.g. user1@domainname.com) |
| profileRequest | ProfileRequestCapture | Details of the request |
In the profileRequest element, the profileGuid should be specified as:
| Profile | GUID |
| Email Validation | 20B3F459-7D04-42AD-B7E2-AA1D5FE07E82 |
Email Validation Criteria
The Email validation criteria should be entered into the email field:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → email
Email Validation Input XML
The following samples demonstrate a request data object containing an email address for validation.
<!-- request input data - email and telephone -->
<req:requestdata>
<!-- email input data -->
<req:email>first.lastname@company.co.uk</req:email>
</req:requestdata>"requestdata": {
"email": ["first.lastname@company.co.uk"]
}
}Email Validation Additional Options
Email Validation options can be specified by providing the key value pairs specified below to the ProfileRequestCaptureData → additionalData property.
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → additionalData
Type: IdmDataArrayAdditionalData
| Key Mnemonic | Key Value | Description |
|---|---|---|
| EMAIL_TIMEOUT | Timeout Value in milliseconds (200 < EMAIL_TIMEOUT < 30000) | This value specifies how long the service is allowed to wait for all real-time network level checks to finish. Real-time checks consist primarily of DNS and SMTP level verification. Timeout time is in milliseconds. A minimum value of 200ms is required. |
NOTE: If no email validation timeout value is specified in the additionalItems list, or the value is not a valid positive number, the service will default to using a value of 30 seconds
If a value of less that 200 is speified, the service will set the timeout at 200 mS
If a value of greater then 30000 mS (30 seconds) is specified the service will set the timeout at 30000 mS
The following samples demonstratessetting the email validation timeout vale to 10 seconds.
<req:additionaldata>
<data:item>
<data:key>email_timeout</data:key>
<data:value>10000</data:value>
</data:item>
</req:additionaldata>{
"additionaldata": {
"item": {
"key": "email_timeout",
"value": "10000"
}
}
}Bank Input XML
The following XML sample demonstrates a request data object containing both an address and two bank accounts for validation.
<!-- request input data - bank account validation -->
<req:requestdata>
<req:address />
<req:bank>
<data:accountnumber>12345678</data:accountnumber>
<data:sortcode>110167</data:sortcode>
</req:bank>
<req:filters tmp="?" />
<req:options>
<req:offset>0</req:offset>
<req:maxreturn>10</req:maxreturn>
</req:options>
<req:additionaldata tmp="?" />
</req:requestdata>JSON sample:
{
"customerreference": "test",
"profileguid": "39944560-4137-489a-a72d-64f0f3524b08",
"configurationid": "1",
"requestdata": {
"bank": [{
"accountnumber": "12345678",
"sortcode": "110167"
}],
"options": {
"offset": "0",
"maxreturn": "100",
"countrycodeformat": "iso_3"
}
}
}Output Format
The results of the GB Email Verification Web Service search are returned in a ProfileResponseDetails structure with a responseType of 'VALIDATE'.
The ProfileResponseDetails structure contains a single data structure which holds an array of records containing the returned validation data per input number.
ExecuteCaptureResponse → ProfileResponse [0] → ProfileResponseDetails [0] → ValidateResponse → ValidateResponseData
The returned data structure is detailed below:
Type: ValidateResponseData
| Field Name | Type | Description |
|---|---|---|
| input | String | The input Bank Account and Sortcode |
| status | Enumeration | SUCCESS if the validation has taken place, FAILURE otherwise |
| validationCodes | IdmDataArrayAdditionalData | Array of key value pairs containing the validation response codes for the input |
Sample Output XML
Search XML requesting more data:
The following output XML demonstrates the ProfileResponse for the Email Address Component. The component name is Email Validation and the response type is VALIDATE.
The validation results for each email address will be returned in the same order as input. The array of ValidateResponse data structures contain the individual response details. A series of key value pair response codes are returned for each address, which contain data supplier specific summaries of the input.
<!-- email component response -->
<req:profileresponse>
<req:transactionguid>1d39bec2-7f7e-42b9-bdfd-3909bf20f44d</req:transactionguid>
<req:componentname>email validation</req:componentname>
<req:componentstatus>success</req:componentstatus>
<req:componentaction>match</req:componentaction>
<req:responsetype>validate</req:responsetype>
<req:notes>[]</req:notes>
<!-- billing invoice -->
<req:invoice>
<req:invoicelist>
<req:invoiceguid>f7210d60-f4bf-4024-82ed-75a8eb5c0681</req:invoiceguid>
<req:billinginformationguid>477b8bfb-b3ea-4fa5-9015-431047e046ec</req:billinginformationguid>
<req:billingpoints>21</req:billingpoints>
<req:creditsused>1</req:creditsused>
<req:datasetinvoices>
<req:datasetcode>email</req:datasetcode>
<req:billingpoints>1</req:billingpoints>
<req:recordsreturned>1</req:recordsreturned>
<req:datalicenceguid>477b8bfb-b3ea-4fa5-9015-431047e046ec</req:datalicenceguid>
</req:datasetinvoices>
</req:invoicelist>
</req:invoice>
<!-- response data -->
<req:validateresponse>
<req:recordsreturned>1</req:recordsreturned>
<req:responsecount>1</req:responsecount>
<!-- response per input email -->
<req:response>
<req:input>first.lastname@company.co.uk</req:input>
<req:status>success</req:status>
<req:validationcodes>
<data:item>
<data:key>issyntaxgood</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>syntaxerrorposition</data:key>
<data:value>-1</data:value>
</data:item>
<data:item>
<data:key>isdomainspecificsyntaxgood</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>domainspecificsyntaxerrorposition</data:key>
<data:value>-1</data:value>
</data:item>
<data:item>
<data:key>isdnsgood</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>issmtpservergood</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>issmtpmailboxgood</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>iscatchalldomain</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>isrecognisedtld</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>iscountryspecific</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>isalias</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>isfree</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>isestablished</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>isvulgar</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>issmsdomain</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>isrole</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>isgood</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>isdeliverable</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>isbusinessaddress</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>isbogus</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>box</data:key>
<data:value>first.lastname</data:value>
</data:item>
<data:item>
<data:key>domain</data:key>
<data:value>company.co.uk</data:value>
</data:item>
<data:item>
<data:key>topleveldomain</data:key>
<data:value>.uk</data:value>
</data:item>
<data:item>
<data:key>topleveldomaindescription</data:key>
<data:value>united kingdom</data:value>
</data:item>
<data:item>
<data:key>nomxrecords</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>bogussmsaddress</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>garbage</data:key>
<data:value>unknown</data:value>
</data:item>
<data:item>
<data:key>mailboxisfull</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>mailboxisbusy</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>disposableemail</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>spamtrap</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>knownspammer</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>blacklisteddomain</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>knowncomplainer</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>knowngreylister</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>optinrequired</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>iswhitelistonly</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>connectionrefused</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>emailisbad</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>bot</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>greylisttactic</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>mailservertemporarilyunavailable</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>serverconnecttimeout</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>mailboxtimeout</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>temporaryreject</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>misspelleddomain</data:key>
<data:value>false</data:value>
</data:item>
</req:validationcodes>
</req:response>
</req:validateresponse>
</req:profileresponse>{
"profileheader": {
"profileguid": "20b3f459-7d04-42ad-b7e2-aa1d5fe07e82",
"profilename": "email",
"transactionguid": "076b89ea-f6d6-4a3c-aba5-38ccc89f3c4f",
"transactiontimestamp": 1433167116839,
"profilestatus": "success",
"remarks": null
},
"profileresponsedetails": [ {
"transactionguid": "a3c9c522-0a44-4e75-93fc-af1052520233",
"componentname": "email validation",
"componentstatus": "success",
"componentaction": "match",
"responsetype": "validate",
"notes": "[]",
"invoice": {
"invoicelist": [ {
"invoiceguid": "109a0d0f-0769-49f0-95cc-7cd123eef4f5",
"billinginformationguid": "477b8bfb-b3ea-4fa5-9015-431047e046ec",
"datalicencedescription": null,
"billingpoints": 1,
"creditsused": 1,
"datasetinvoices": [ {
"datasetcode": "email",
"billingpoints": 1,
"recordsreturned": 1,
"datalicenceguid": "477b8bfb-b3ea-4fa5-9015-431047e046ec"
}]
}],
"tmp": null
},
"captureresponse": null,
"validateresponse": {
"resultstatus": null,
"recordsreturned": 1,
"responsecount": 1,
"response": [ {
"input": "first.lastname@company.co.uk",
"status": "success",
"validityflag": "valid",
"validationcodes": {
"item": [
{
"key": "issyntaxgood",
"value": "true"
},
{
"key": "syntaxerrorposition",
"value": "-1"
},
{
"key": "isdomainspecificsyntaxgood",
"value": "true"
},
{
"key": "domainspecificsyntaxerrorposition",
"value": "-1"
},
{
"key": "isdnsgood",
"value": "true"
},
{
"key": "issmtpservergood",
"value": "true"
},
{
"key": "issmtpmailboxgood",
"value": "unknown"
},
{
"key": "iscatchalldomain",
"value": "true"
},
{
"key": "isrecognisedtld",
"value": "true"
},
{
"key": "iscountryspecific",
"value": "false"
},
{
"key": "isalias",
"value": "false"
},
{
"key": "isfree",
"value": "unknown"
},
{
"key": "isestablished",
"value": "false"
},
{
"key": "isvulgar",
"value": "false"
},
{
"key": "issmsdomain",
"value": "false"
},
{
"key": "isrole",
"value": "false"
},
{
"key": "isgood",
"value": "unknown"
},
{
"key": "isdeliverable",
"value": "unknown"
},
{
"key": "isbusinessaddress",
"value": "unknown"
},
{
"key": "isbogus",
"value": "false"
},
{
"key": "box",
"value": "first.lastnam"
},
{
"key": "domain",
"value": "company.co.uk"
},
{
"key": "topleveldomain",
"value": ".uk"
},
{
"key": "topleveldomaindescription",
"value": "commercial"
},
{
"key": "nomxrecords",
"value": "false"
},
{
"key": "bogussmsaddress",
"value": "unknown"
},
{
"key": "garbage",
"value": "unknown"
},
{
"key": "mailboxisfull",
"value": "false"
},
{
"key": "mailboxisbusy",
"value": "false"
},
{
"key": "disposableemail",
"value": "false"
},
{
"key": "spamtrap",
"value": "false"
},
{
"key": "knownspammer",
"value": "false"
},
{
"key": "blacklisteddomain",
"value": "false"
},
{
"key": "knowncomplainer",
"value": "false"
},
{
"key": "knowngreylister",
"value": "false"
},
{
"key": "optinrequired",
"value": "false"
},
{
"key": "iswhitelistonly",
"value": "false"
},
{
"key": "connectionrefused",
"value": "false"
},
{
"key": "emailisbad",
"value": "false"
},
{
"key": "bot",
"value": "false"
},
{
"key": "greylisttactic",
"value": "false"
},
{
"key": "mailservertemporarilyunavailable",
"value": "false"
},
{
"key": "serverconnecttimeout",
"value": "false"
},
{
"key": "mailboxtimeout",
"value": "false"
},
{
"key": "temporaryreject",
"value": "false"
},
{
"key": "misspelleddomain",
"value": "false"
}
],
"tmp": null
}
}]
},
"verifyresponse": null,
"traceresponse": null
}]
}Error in the Validation Process
As the Validation process involves several steps, it's possible that one of these steps might fail for some reason. In this case, the response will be a valid response but there will be some Validation Codes indicating the problem.
Sample XML and JSON Responses with some Validation Problem:
<req:profileresponse>
<req:transactionguid>1d39bec2-7f7e-42b9-bdfd-3909bf20f44d</req:transactionguid>
<req:componentname>email validation</req:componentname>
<req:componentstatus>success</req:componentstatus>
<req:componentaction>match</req:componentaction>
<req:responsetype>validate</req:responsetype>
<req:notes>[]</req:notes>
<!-- billing invoice -->
<req:invoice>
<req:invoicelist>
<req:invoiceguid>f7210d60-f4bf-4024-82ed-75a8eb5c0681</req:invoiceguid>
<req:billinginformationguid>477b8bfb-b3ea-4fa5-9015-431047e046ec</req:billinginformationguid>
<req:billingpoints>21</req:billingpoints>
<req:creditsused>1</req:creditsused>
<req:datasetinvoices>
<req:datasetcode>email</req:datasetcode>
<req:billingpoints>1</req:billingpoints>
<req:recordsreturned>1</req:recordsreturned>
<req:datalicenceguid>477b8bfb-b3ea-4fa5-9015-431047e046ec</req:datalicenceguid>
</req:datasetinvoices>
</req:invoicelist>
</req:invoice>
<!-- response data -->
<req:validateresponse>
<req:recordsreturned>1</req:recordsreturned>
<req:responsecount>1</req:responsecount>
<!-- response per input email -->
<req:response>
<req:input>first.lastname@company.co.uk</req:input>
<req:status>failure</req:status>
<req:validityflag>unknown</req:validityflag>
<req:validationcodes>
<data:item>
<data:key>errordescription</data:key>
<data:value>call to mail server timeout</data:value>
</data:item>
<data:item>
<data:key>errordescriptioncode</data:key>
<data:value>be070001</data:value>
</data:item>
<data:item>
<data:key>misspelleddomain</data:key>
<data:value>false</data:value>
</data:item>
</req:validationcodes>
</req:response>
</req:validateresponse>
</req:profileresponse>{
"profileheader": {
"profileguid": "20b3f459-7d04-42ad-b7e2-aa1d5fe07e82",
"profilename": "email",
"transactionguid": "076b89ea-f6d6-4a3c-aba5-38ccc89f3c4f",
"transactiontimestamp": 1433167116839,
"profilestatus": "success",
"remarks": null
},
"profileresponsedetails": [ {
"transactionguid": "a3c9c522-0a44-4e75-93fc-af1052520233",
"componentname": "email validation",
"componentstatus": "success",
"componentaction": "match",
"responsetype": "validate",
"notes": "[]",
"invoice": {
"invoicelist": [ {
"invoiceguid": "109a0d0f-0769-49f0-95cc-7cd123eef4f5",
"billinginformationguid": "477b8bfb-b3ea-4fa5-9015-431047e046ec",
"datalicencedescription": null,
"billingpoints": 1,
"creditsused": 1,
"datasetinvoices": [ {
"datasetcode": "email",
"billingpoints": 1,
"recordsreturned": 1,
"datalicenceguid": "477b8bfb-b3ea-4fa5-9015-431047e046ec"
}]
}],
"tmp": null
},
"captureresponse": null,
"validateresponse": {
"resultstatus": null,
"recordsreturned": 1,
"responsecount": 1,
"response": [ {
"input": "first.lastname@company.co.uk",
"status": "success",
"validityflag": "unknown",
"validationcodes": {
"item": [
{
"key": "errordescription",
"value": "call to mail server timeout"
},
{
"key": "errordescriptioncode",
"value": "be070001"
},
{
"key": "misspelleddomain",
"value": "false"
}
],
"tmp": null
}
}]
},
"verifyresponse": null,
"traceresponse": null
}]
}<br><br>Error Information
Information on possible error codes is given here: Error Code Information