Skip to main content

Email Validate API

Overview

You will find this API useful if you need to obtain e-mail validity and status.

Experian Email Validate API service quickly and accurately identifies whether or not an email address is valid and deliverable. It also offers suggestions for a correct address enabling users to select a more accurate and verified e-mail.

Email Validate is a RESTful API service. REST is a style of software architecture that provides a convenient and consistent approach to requesting and retrieving data.

Email Validate API returns data in JSON format. JSON is a common Internet format that provides a simple method of representing arbitrary data structures. According to json.org, it is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.

 

Workflows

Email Validate API supports both asynchronous and synchronous communications. Each integration has its own advantages and disadvantages, depending on the usage scenario.

AsynchronousI want more flexibility

With asynchronous integration, you can fire your request to the Email Validate service without having to wait for the result to return. The result can be retrieved from the service later, providing more flexibility.

Note that the result will be removed if it is not accessed within 5 minutes. Also, you may have to make several attempts to retrieve the results if there is a delay in retrieving them back.

SynchronousI want the results as soon as possible

In contrast, with the synchronous integration when a request is fired to the Email Validate service, you will receive your result within the request call itself. You therefore have to wait for the request to finish processing before you can continue with the workflow.

Sample code

You can use our REST sample code for validating address, phone and email data. See Capture sample code guide for details

Get sample code

Authentication

Contact your Experian sales representative to create an account.

An Auth-Token is used to authenticate the service. Your Auth-Token must be specified in the request header or passed as a query parameter in the URL. 

Existing customers can view and manage their tokens via the Self Service Portal. For more information about tokens visit our portal help page.

Security

This API supports Cross Origin Resource Sharing (CORS). This is a specification developed by W3C that allows browsers to make cross-domain requests thus enabling client-side integrations. When making a request, the browser will add an origin request header. The API will then respond with a CORS specific response header denoting the origin domains allowed to make requests to the API.

CORS supported OS and browsers:

  • iOS devices (all versions)
  • Safari, IE, and Chrome

 

Permitted URLs

We strongly recommend that you specify the permitted URLs to be used for email capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See our Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs.

 

Asynchronous integration

With this integration, you can fire your request to the Email Validate service without having to wait for the result to return.

The result can be retrieved from the service later, providing more flexibility.

Note that the result will be removed if it is not accessed within 5 minutes. Also, you may have to make several attempts to retrieve the results if there is a delay in retrieving them back.

Alternative integration: synchronous

How does it work?

The client specifies an action using an HTTP POST followed by an HTTP GET to request the result.

Synchronous integration

With this integration when a request is fired to the Email Validate service, you will receive your result within the request call itself.

You therefore have to wait for the request to finish processing before you can continue with the workflow.

Alternative integration: asynchronous

How does it work?

The client specifies an action using an HTTP POST to request the result.

API reference

The Email Validate API reference defines the available resources, the parameters to include with each request and the expected response values. 

 https://api.experianmarketingservices.com/<resource>/EmailValidate/1.0/<token>/

Asynchronous

Synchronous

Headers

Auth-Token: [Token] 
Content-Type: application/json

When you make an authenticated API request, your request has to specify the Auth-Token HTTP request header as shown above. Alternatively, the token (auth-token) can be passed as a query parameter in the URL endpoint.

For example: https://api.experianmarketingservices.com/query/EmailValidate/1.0/<token>/

If your token is setup with URL restriction, you will need to ensure that the Permitted URL (in HTTP Referer Header) is sent along with your request.

We strongly recommend that you specify the permitted URLs to be used for email capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See our Self Service Portal help for more information about tokens and full instructions on how to set your permitted URLs.

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"
}

POST /sync/queryresult

Synchronous - posts an email address to the service to be validated and, once complete, returns the results of the validation.

Request

https://api.experianmarketingservices.com/sync/queryresult/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 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"
}

 

API output elements

The response from this API will contain a section (represented as a JSON object) for each type of data returned. Response elements that may be included in this section:

ElementDescription

Email

Submitted email address, e.g. "anemailexample@gmail.com"

Certainty

Indicates the email status, e.g. "illegitimate". See Validation Responses for a full list.

Message

Indicates the summary of request's status:

  • OK or Mailbox Full will be returned if the request has been successful and valid responses are returned
    Mailbox Full will be returned only when the user's mailbox is full. In all other cases of 'undeliverable' responses, the OK status will be returned.
  • No response will be returned if the request has not been successful. See Lookup Status Messages for details.

Corrections

List of email corrections returned, if available

Email Validate API can also return email corrections for syntax mistakes in an email. A maximum of 8 email corrections can be returned in the responses, if available.

VerboseOutput

Additional information regarding Certainty responses when verbose flag is True, e.g. "mailboxDoesNotExist". See Validation Responses for a full list.

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"]
}

Status codes

These are the HTTP codes the service will explicitly return; however, client programs should be prepared to handle any of the standard HTTP codes.

CodeMessage(s)Description
200 OK Request processed successfully.
400

Bad Request

Request failed due to malformed syntax. Check the response header for more information.

401 Unauthorized Provided token is incorrect. Please check your token: go to Self Service Portal > Licenses.
403 Forbidden Request is not authorized to use the service.
404 Not Found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
409 Conflict Result is not ready. Please resubmit the request to try and retrieve the result again.
500 Internal Server Error We have encountered an unexpected server error. Please contact support if the problem persists.
503 Service Unavailable The server is currently unavailable. Please try again later or contact support if the problem persists.

 

 

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.