Skip to main content

Email Validate Sample Code

Email Validate is a hosted web service that allows customers to correct or remove bad email addresses at the point of entry.

Validated emails will allow you to preserve your sender reputation and maximize marketing ROI from your email database.

The implementation option available is SaaS. 

Implementation overview and expected timescales

The following steps cover a typical implementation and expected timescales for Email Validate sample code:

  1. Set up web services. The Experian Email Data web service only requires a token to be sent to activate their services.
    Contact Experian sales representative to create an account and get access to the API.
  2. Integrate sample code into a single touch point* (8 to 16 hours).
    *In order to make use of the technology a set of pages must be hosted on the same site as the target application. The estimate of one day assumes a skilled developer who understands the related technologies and modifying the target application.
  3. Test and review with project stakeholders (8 hours).
  4. Replicate across remaining touch points (4 hours per touch point).
  5. Deploy to production environment (2 hours).

Integrating into your website

The Email Validate sample code is typically provided by the customer account manager or technical consultant assigned to assist you with your implementation. Contact them for any questions.

Integration notes

  • This walkthrough assumes that the Email Validate code resides in the same directory as the target page. If the code resides in a different directory, the paths can be adjusted. See Target Page Modifications for details.
  • If you are already using jQuery and jQuery UI, you can leave the reference to your corresponding JavaScript and CSS files in order to give the address layout the same style as the html page. If you do not already have jQuery UI implemented, you can modify the provided CSS to match your styling.

The integration consists of 3 steps: preparing the form, testing the functionality and integrating.

1. Prepare the sample form

  1. Extract the sample code zip file to create new directories for the sample code, and documentation.
  2. Copy the contents of the extracted sample code directory to the main directory of the application you wish to integrate Pro Web with.

JSP is provided in the form of a war file which will need to be deployed as per the documentation of your Web Server.

2. Test the functionality

  1. Open the email_proxy.aspx file. Search for the token string field and set the value to the security token that you are subscribed to.
  2. Once you have confirmed connectivity, open a web browser and navigate to qas_test.html within your application directory structure.
  3. Enter the information below and click Submit to validate the contact details. This confirms that the Email Validate functionality is working outside of your application.

Example

The validated e-mail should look similar to this:


3. Integrate into your website/application

Once all configuration and testing has been completed on the sample form, you can begin to work on integrating Email Validate into your application.

The qas_test.html contains the code that will need to be added to the target page. There are a small number of requirements that if followed should provide for an easy integration.

Validation function

QAS_Verify():Call this to use the Email Validation service.

Target page modifications

  1. Include the following in the <head> section of your page:
    <linkrel="stylesheet"type="text/css"href="jquery/css/qas/jquery-ui-1.8.6.custom.css" />
    <linkrel="stylesheet"type="text/css"href="qas.css" />
    <scripttype="text/javascript"src="jquery/js/jquery-1.4.2.min.js">
    <scripttype="text/javascript"src="jquery/js/jquery-ui-1.8.6.custom.min.js">
    <scripttype="text/javascript"src="jquery/js/jquery.jsonp-2.4.0.js">
    <scripttype="text/javascript" src="jState.js">
    <scripttype="text/javascript"src="qasConfig.js">
    <scripttype="text/javascript"src="email.js">
    

    Set src to the actual location of the file.

  2. If using a form, set the form to return false on submit, for example:
    <form id="checkout" action="thankyou.aspx" method="post" onsubmit="return false;" >
  3. Add the appropriate validation function to an onclick event tied to the data submission, for example
    <input id="subButton" type="submit" value="Submit" onclick="return QAS_Verify()"/>

Changes to qasConfig.js

  1. Set IDs:
    1. Set EMAIL_FIELD_IDS to the id attributes of your target email fields.
    2. The delivered JavaScript file comes configured for three sets of contact information on a single form, but this can be modified for the appropriate number for your page simply by adding or removing an array of attributes from the ADDRESS_FIELD_IDS, COUNTRY_FIELD_IDS, EMAIL_FIELD_IDS or PHONE_FIELD_IDS.
  2. Set validation invocation options:
    1. preOnclick will call a function to be run just prior to address validation and will not proceed until true is passed back.
    2. postOnClick can trigger a function call after validation. It can also be used in the case that you are not using a form for submission.
    3. buttonID is used to submit your form. By using the button id of your submit button, the code will use this button to submit your form after address validation has been performed.
  3. Email search timeout:

    You can specify a timeout for each email search. The searches will timeout after the specified period of time if no response is returned within that period. If the timeout occurs, the email result of ‘Unknown’ will be returned.

    To set the timeout, find EMAIL_RESULT_TIMEOUT and specify the time in seconds(s).

Additional optional parameters can be set at the top of the JavaScript file and their usages are explained in the comments found in the JavaScript.

Changes to email_proxy.aspx

  1. Set STRING TOKEN field to the security token that you are subscribed to.
  2. STRING MACHINEURI is already configured to point to the hosted location of QAS Email Validation REST Service. The value will have to be amended if the QAS hosted REST Service location is updated or changed. Currently, the URL is 'https://api.experianmarketingservices.com/query/'.

List of main configuration files

  • qas_test.html
    A sample webpage which demonstrates the implementation codes of Email Validate.
  • qas.css
    A cascading style-sheet which provides styling to the mark-ups texts in qas_test.html.
  • qasConfig.js (formally qas.js)
    A JavaScript file which provides general options and call-back handlers for the supported services.
  • email_proxy.aspx
    A proxy class which provides functionality to communicate web requests to Email web service.
  • email.js
    A JavaScript file which contains the business logics and workflows for email validations.

Testing your implementation

It is important to confirm that you can replicate the expected behavior of the Email Validate code and that the implementation does not negatively impact your existing functionality.

Standardization and population of email information

It is important that the configuration of the returned email validation matches your business requirements. Validate the sample information provided below across all touch points that the Email Validate code is integrated with.

The code can return errors for several different types of email issues. The error types are listed in the qasConfig.js in the EMAIL_ERR_MESSAGES array.

See below for examples of email error scenarios that can occur.

Email contains errors

Issue: The web service reports that the username does not exist at that domain. The customer should edit the email address in the boxes provided and continue.

Email: nottaken@aol.com

 

Email contains errors - suggestions available

Issue: The web service reports that the e-mail contains a syntax error and offers a suggested correction.

Email: emailexamples@gmail.com

The user can choose to:

  • Select the Verified email suggestion and Continue:

  • Select the original email and continue, if a suggestion has been selected already:
  • Edit the email address in the box provided and Continue:

Full list of errors

  • Username or domain does not exist, or mailbox is suspended or disabled
  • Email domain could not be reached or verified
  • Email mailbox is full

Deployment

Accessing the functionality

Contact your Experian sales representative to create an account.

To get access, you will require a token which is retrieved from Self Service Portal → Licenses.

Deploying the service

Once the sample code is integrated and fully tested across all touchpoints of your application it will be ready to be moved into a production environment.

In order to make this transition as smooth as possible, make sure to:

  • Confirm that your machine can access the Email Validate web service
  • Roll the integrated application code out to your machine and
  • Test your implementation

Email data reference

Email Validate returns validation information based upon the input email address.

POST /query

Asynchronous - posts an email address to the service to be validated. Make a GET /result request to retrieve the results.

Request

https://api.experianmarketingservices.com/query/EmailValidate/1.0/

Note that URLs that do not specify the version number will default to version 1.0.

Parameters

Parameter Valid Values / Examples
Email

The input email address, e.g. "anemailexample@gmail.com". 

Timeout 
(optional)

The email validation search timeout in seconds. If a timeout occurs, the email certainty status of Unknown will be returned.

  • Default value: 3 seconds (if this parameter is omitted)
  • Maximum: 15 seconds
  • Minimum: 3 seconds

This setting will have an impact on performance and accuracy. A low value (e.g. 3 seconds) might lead to an inaccurate email result of Unknown status; while a higher value will impact the performance of the returned result.

Verbose 
(optional)

A boolean value (true/false) to determine whether to return VerboseOutput information. 

  • Default value: False

Sample request object

{
   "Email": "support@gmailcom", 
   "Timeout":"5", 
   "Verbose":"True"
}

Response

Sample response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Location:https://api.experianmarketingservices.com/result/EmailValidate/1.0/00000000-0000-0000-0000-000000000000
Date: Mon, 01 July 2014 08:15:29 GMT

 

GET /result

Asynchronous - retrieves the results of an Email Validate POST /query request. The URL for this request is returned in the Content-Location field name of the response header when making the initial query.

Request

Sample Request

GET https://api.experianmarketingservices.com/result/EmailValidate/1.0/00000000-0000-0000-0000-000000000000

Response

Sample response

HTTP/1.1 200 OK
Content-Length: 30
Content-Type: application/json
Message: OK
QueryId: 00000000-0000-0000-0000-000000000000
Date: Mon, 01 July 2014 08:15:56 GMT
 
{
      "Email": "support@gmailcom",
      "Certainty": "undeliverable",
      "Message": "OK",
      "Corrections": [
         "support@gmail.com"
      ],
      "VerboseOutput": "syntaxFailure"
}

Validation responses

The validation status of the e-mail can be found in the response’s body under Certainty:

CertaintyVerboseOutput 
(shown only if the 'Verbose' parameter is set to 'True')
Description
verified verified Mailbox exists, is reachable, and not known to be illegitimate or disposable.

undeliverable

mailboxDisabled The user mailbox has been disabled.
mailboxDoesNotExist The user mailbox does not exist at this domain.
mailboxFull The user mailbox is full.
syntaxFailure The syntax of the email address is incorrect.

unreachable

unreachable The domain is not responding to validation requests or does not have any active mail servers.
unresolvable The domain cannot be resolved.

illegitimate

illegitimate Seed, spamtrap, black hole, technical role account or inactive domain.
roleAccount Role accounts such as support@, sales@, info@.
typoDomain The domain was close to a common domain and although it exists, it is highly unlikely to be correct.
localPartSpamTrap Known local portions of the email that may indicate spam traps.
disposable disposable Domain is administered by a disposable email provider (e.g. Mailinator).

unknown

unknown We were unable to conclusively verify or invalidate this address.
timeout The request timed out due to the host domain not responding in time.
acceptAll The domain is accept-all, so the username cannot be validated.
relayDenied Result was validated at the incorrect mail exchanger.

Lookup status messages

The status of the call can be found in the response’s header under Message:

Message
(in JSON Response Header)
Comments
OK Request has been successfully sent and valid responses are being returned back.
Bad query: Malformed JSON in request

Request has been successfully sent but no responses are being returned. Possible causes:

  • Missing a mandatory parameter
  • Invalid JSON format
  • Blank values are being sent
Bad query: Invalid input parameter value Check the parameter values you’ve entered are valid.
Bad query: Email is too long The entered email address is too long.
Bad query: Missing security token The token is missing in the request's header or the URL.
Bad query: Missing query id parameter in URL The query id parameter is missing in the URL.
Resource not found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
Unauthorized: Token not recognized Provided token is incorrect. Please check your token: log into the Self Service Portal > Licenses.
Forbidden: Product not matched Request is not authorized to use the service.
Forbidden: Entitlement disabled Your token has run out of credits. To find token information, log into the Self Service Portal > Licenses.

Note that the specific validation status message can also be found in the response body under Message.

Sample error

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:24:02 GMT
Message: Provider failure
QueryId: 5bd1bb45-85b7-4a25-aeb4-7bad67b7249b

Response Body
{}

Sample success

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:31:00 GMT
Message: OK
QueryId: 9da8c5cc-b27b-4026-b7a2-f7196367a085
 
Response Body
{
   "Email": "Anemailexample@gmail.co",
   "Certainty": "illegitimate",
   "Message": "OK",
   "Corrections": ["Anemailexample@gmail.com"]
}

Troubleshooting

SSL certificate errors

Your SSL certificate might have expired. To manually update your deployment:

  1. Get the files:
    Download ZIP
  2. Extract the files.
  3. Install Root.crt in the Trusted Root Certificates Authorities Store.
  4. Install the following files in the Intermediate Certificate Authorities Store:
    • Intermediate1.crt
    • Intermediate2.crt
  5. Install api.experianmarketingservices.com.cer in the Personal Certificate Store.
  6. For further help contact your local support team.

Copyright ©, 2014-2017. All rights reserved.