Skip to main content

Email Validate API

Overview

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

This API uses TLS 1.2 encryption. Find out more.

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

Postman collections

We now have pre-configured Postman collections for our APIs.

You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.

Get Postman collections

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. Find out more about tokens. To view and manage your tokens, log into the Self Service Portal

Security

We strongly recommend that you secure your integration to prevent malicious use. 

If you don’t specify CORS origin domains, URLs or IPs that will be allowed to use your token, there’s a risk of other websites accessing and using your integration which you may be charged for.

Depending on your setup, you can specify:

  • CORS origin domains

    Cross Origin Resource Sharing (CORS) is a specification developed by W3C that allows browsers to make cross-domain requests. When making a request to our service, the browser will add an origin request header. Our service will then respond with a CORS specific response header denoting the origin domains allowed to make requests.
    To secure your integration, specify the origin domains that will have access to your integration. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five origin domains.

  • Permitted URLs
    If you're integrating your token into a web form, you can also specify the permitted URLs to ensure that only requests from your domains are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five URLs. See an example of a successful response.
  • Whitelisted IPs/IP ranges
    If you're integrating your token to an API service on your server, specify the IP addresses or IP address ranges to ensure that only requests from your servers are authenticated. Go to Self Service Portal > Licenses. Click Edit for the required token and enter up to five IPs/IP ranges. See an example of a successful response.

 

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, parameters and the expected response values. 

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@example.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.
Profanity The email address contains profanity. Contact your account manager to activate this response.
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.
Forbidden: Your IP address is not whitelisted.  This IP address does not have access to your integration. To whitelist it, log into the Self Service Portal > Licenses.
Forbidden: Your origin domain is not defined. This domain does not have access to your integration. To allow access to it, log into the Self Service Portal > Licenses.

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

Response examples

Sample error

Response Header
Content-Type: application/json
Date: Wed, 11 Sep 2013 07:24:02 GMT
Message: Unauthorized: Token not recognized
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
Access-Control-Allow-Origin: https://www.example.com
Access-Control-Expose-Headers: Message, Content-Location
Response Body { "Email": "Anemailexample@example.co", "Certainty": "illegitimate", "Message": "OK", "Corrections": ["Anemailexample@example.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 certificates might have expired. You will need to update your certificates with the relevant certificate files. 
  1. Download both Entrust and GlobalSign files. 
  2. Extract the files.
  3. Install the certificates in the correct certificate stores as shown below:
  Trusted RootIntermediatePersonal
Entrust

EntrustCA
EntrustRootCA-G2

EntrustCA-L1K

api.experianmarketingservices.com

GlobalSign

GlobalSignRoot-R1

GlobalSigncloudsslsha2g3r3

EDQincapsula

For further help contact support. 

Connection issues

In order to use our services, you need to ensure that certain IP addresses (listed below) are accessible to you (i.e. not blocked by your firewalls). 

  • 167.107.82.39
  • 45.60.31.210
  • 45.60.32.212
  • 45.60.33.210
  • 45.60.34.212
  • 45.60.35.210
  • 45.60.36.212
  • 45.60.37.210
  • 45.60.38.212
  • 45.60.39.210
  • 45.60.40.212