Email Validation API

Overview

Provides email address validation 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://api.hopewiser.com.au/email-verify/verify

where the request body contains the email address to verify. For example:

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

The service can respond with a status of either Completed or Processing. If the status is Processing, then the result should be obtained by making periodic GET requests for the returned resource ID. For example:

https://api.hopewiser.com.au/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

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://api.hopewiser.com.au/email-verify/provisioned

The service will respond 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
}

An email validation is initiated by sending a POST request to the URL:

https://api.hopewiser.com.au/email-verify/verify

Where the request body is a JSON object comprising a single mandatory property

Property/Key	Description
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 manner. 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 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.au).

{
  "id": "afe5bc5f-1078-422b-9a342-eba02ba8a395",
  "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. For example:

https://api.hopewiser.com.au/email-verify/verify/{id}

The ID should be replaced with the ID provided in the initial submission. For example:

https://api.hopewiser.com.au/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 10 minutes from the initial request submission.

The response body will have the same structure as that returned for the initial POST request.

Email Classification Codes

Classification Codes	Description
Deliverable	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 to.
Unknown	Hopewiser cannot determine whether the email address can be delivered to or not.
Unverifiable	The email server has been identified as a Catch All, the email address is potentially deliverable to.

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 them as undetermined.

Status Codes	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 does not 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.
405 (Method Not Allowed)	The HTTP method is not allowed for the given URL. For example, performing a GET request when the unique resource identity has been omitted from the URL.
415 (Unsupported Media Type)	The request body must be in JSON format (i.e. have the Content-Type header value application/json).
5xx (Server Error)	The email address validation could not be completed due to an unexpected server error.

Status Codes

For all status codes, other than 200 (OK) and 202 (Accepted), a textual description of the response may also be provided. For example:

{
     "status": "Not Found",
     "statusDetails": {
        "description": "The specified resource does not exist or is no longer available"
     }
}