Skip to main content

Email Validation API

Overview

  • Provides email address validtion using standard URL requests.
  • The service follows RESTful principles – accepting HTTP requests and returning JSON response documents.

Quick Start

  • To use this functionality you will need to buy an Email Validation click bundle from the Shop located in our Portal. Register for the Portal here.
  • An email address is validated by sending a POST request to the URL:
https://cloud.hopewiser.com/email-verify/verify

 

    where the request body contains the email address to verify. For example:
{
"email": "support@hopewiser.com"
}
  • If the service responds with the status Processing, then the result should be obtained by making periodic GET requests for the returned resource ID. For example:
https://cloud.hopewiser.com/email-verify/verify/afe5bc5f-1078-422b-9a342-eba02ba8a395
  • Authentication is achieved using HTTP Basic Authentication, where both the token username and password are supplied in the Authorization request header. To secure this information all requests should use the https:// protocol, in preference to standard http://.

Basics

How do I determine if my token can use the Email Validation API?

The Email Validation API is only available when your Portal account contains an active Email Validation plan. You can determine this by sending a GET request to the URL:

https://cloud.hopewiser.com/email-verify/provisioned
  • The service will response with the HTTP status code 200 (OK) if the token has been successfully authenticated. The response body will be a JSON object comprising a provisioned and optional blocked property.
Property/Key Description
provisioned A boolean indicating if an Email Validation plan has been provisioned for the token.
blocked? An optional string, which if present indicates that the Email Validation plan has been blocked. The string text provides the blocked reason (e.g. “No clicks remaining”).

Example response body:

}
"provisioned": true",
"blocked": "No clicks remaining"
}

 

How do I validate an email address?

The validation of an email address may taken several seconds to complete, therefore it’s impractical for a client to be blocked whilst wait for the result. As such email validation is achieved by first making an initial request and then polling (as needed) until the result is obtained.
An email validation is initiated by sending a POST request to the URL:

https://cloud.hopewiser.com/email-verify/verify

where the request body is a JSON object comprising a single mandatory property; email – a string representing the email address to validate. For example:

{
"email": "support@hopewiser.com"
} 

The service will respond with the HTTP status code 200 (OK) if the validation was completed in a timely manor. Otherwise, the HTTP status code 202 (Accepted) will be returned indicating that the request has been accepted and is being processed.

The response body will be a JSON object comprising an id, status and optional result property.

Property/Key Description
id A string representing a unique resource identity.
status A string providing the validation status; either Processing or Complete.
result? An optional JSON object that will contain the result when the validation is complete.
result?.classification A string representing the result classification for the validated email address. (See Email Classification Codes for a list of possible values.)
result?.status A string representing the result status for the validated email address. (See Email Status Codes for a list of possible values.)
result?.disposable? An optional boolean indicating if the validated email address is a temporary, disposable address.
result?.free? An optional boolean indicating if the validated email address is handled by a well-known free email service provider (e.g. Gmail, Yahoo, Outlook / Live / Hotmail, etc.).
result?.group? An optional boolean indicating if the validated email address may be referring to a well-known group, which could be configured to handle general communication for a whole department or even an entire company (e.g. sales@example.com).

Example Response HTTP Status Codes

{
  "id": "afe5bc5f-1078-422b-9a342-eba02ba8a395": "OK",
  "status": "Processing"
  }
{
   id": "afe5bc5f-1078-422b-9a342-eba02ba8a395
   "status": "Complete",
   "result": {
      "classification": "Unverifiable",
      "status": "ServerIsCatchAll",
      "disposable": false,
      "free": false,
      "group": true
   }
}

If the returned status is Processing, then the validation result may be obtained by periodically sending a GET request to obtain the details for the unique resource identity. For example:

https://cloud.hopewiser.com/email-verify/verify/afe5bc5f-1078-422b-9a342-eba02ba8a395

The service will respond with the HTTP status code 200 (OK) if the validation has completed. Otherwise, the HTTP status code 202 (Accepted) will be returned indicating that the validation is still being processed.
Results can be obtained up to 5 minutes after the email address validation has completed.
The response body will have the same structure as that returned for the initial POST request.

Email Classification Codes

Classification Codes Description
Deliverable The email address can be delivered.
Disposable Email address is associated with a known disposable address provider.
Harmful The email address is potentially harmful and has been identified as associated to a known trap.
Unconfirmed The email address may be deliverable, but Hopewiser are unable to confirm this. (Please review associated status.)
Undeliverable The email address cannot be delivered.
Unknown Hopewiser cannot determine whether the email address can be delivered or not.
Unverifiable The email server has been identified as a Catch All, the email address is potentially deliverable.

Email Status Codes

The following table lists the possible status codes that may be returned for a verified email address.
NOTE: New status codes may be added in the future to allow for expansion. As such, client applications should accept new, unknown status codes and treat then as undetermined.

Classification code Description
ConnectionFailure A connection error occurred whilst performing the email validation.
ConnectionTimeout A connection timeout occurred whilst performing the email validation.
DisposableEmailAddress The email address is for a disposable mailbox or is provided by a known disposable email address provider.
DoesNotExist The email address does not exist.
FormatError The format of the email address is syntactically incorrect.
InternationalUnsupported The external mail exchanger does not support international mailbox names.
ServerIsCatchAll The external mail exchanger accepts fake and non-existent email addresses that are sent to the domain. Therefore, the existence of the individual mailbox cannot be verified.
SpamTrap The external mail exchanger hides a spam trap (honeypot).
Success Deliverable email address that successfully completed verification.
TemporarilyUnavailable The requested mailbox is temporarily unavailable.
UnhandledException One or more unhandled exceptions have been thrown during the verification process.

HTTP Status Codes

The Email Validation service may return one of the following HTTP status codes to indicate the success or failure of a request.

HTTP status code Description
200 (OK) The email address validation has successfully completed.
202 (Accepted) The email address validation request has been accepted and is being processed.
400 (Bad Request) The request is not formatted correctly or is missing a mandatory parameter.
401 (Unauthorized) The request does no contain valid token credentials.
403 (Forbidden) Email address validation may not be enabled for the authenticated token, a token restriction has been observed or no processing clicks are available.
404 (Not Found) The requested resource does not exist or is no longer available.

Authorisation Code