The Email Validation Platform provides real-time and batch validation of email addresses. The platform is accessible via a RESTful web service as well as an automated SFTP service, as described in Parts B and C of this specification, respectively.
The validity of an email address is defined as follows:
| Value | Description |
|---|---|
| verified | Mailbox exists, is reachable, and not known to be illegitimate or disposable. |
| disposable | Domain is administered by disposable email provider (e.g. Mailinator). |
| unreachable | Domain does not exist or has no reachable mail exchangers (see discussion, below). |
| illegitimate | Seed, spamtrap, black hole, technical role account or inactive domain. |
| undeliverable | Mailbox does not exist, or mailbox is full, suspended or disabled. |
| unknown | We were unable to conclusively verify or invalidate this address. |
A role account is an email address that is not associated with a specific person, but rather with an office, position, group or task. Role accounts can be broadly classified as either technical or nontechnical.
-
A technical role account has a local part such as postmaster, abuse or spam. Because such accounts should never be mailed, these addresses are classified as illegitimate.
-
A nontechnical role account has a local part such as sales, support, info, legal, or inquiries. Whether you choose to accept such addresses depends on your use case, and may require case-by-case, manual evaluation. For these addresses, the value of the role field will be true.
A full mailbox is undeliverable, and typically indicative of an inactive account. However, if you would like to accept these, you can identify them by the existence of the full field, containing a value of true.
An email address is unreachable if either no mail exchangers are advertised for its domain or they all persistently reject or do not reply to inbound connections. While almost always indicative of a domain which is not used to receive email, transient configuration or DNS errors on the receiving end may also be at fault.
Whenever possible, the Email Validation platform will provide suggested corrections for addresses that have been deemed invalid. Corrections are handled slightly differently by the RESTful web service and SFTP batch processing components, and these specifics are described in sections B-9 and C-6, respectively.
All corrections returned as part of the services are provided as suggestions only. This is not a guarantee that the email addresses are correct nor that they can be used in any specific manner or are email addresses you are authorized to send to. Please check with your legal department to confirm that the manner in which you plan to use the emails prior to sending email to such recipients.
In addition to validity of an email address, optional verbose output flags can also be returned which provide greater detail about why the email is that validity. This information is only returned when verbose_output is set to True.
| Validity | Verbose Output | 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. | |
| 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. |
The Email Validation Platform is accessible via a RESTful web service for real-time validation. API resources are identified by URLs and interacted with using the standard HTTP methods: GET, PUT, POST and DELETE.
An illustrative example of a real-time query and its result is given in Section B-10.
The client specifies the desired API version in the URL of each request (see Section B-5) so that new versions do not break existing deployments. Whenever the introduction of compatibility-breaking changes is necessary, a new version number will be allocated, but this should be relatively infrequent. The most recent two API versions will be supported at any given time, but only the newest version will be actively maintained.
All API traffic is encrypted via TLS (SSL) and the servers are authenticated via 2048-bit X.509 digital certificates. Client-side (JavaScript) queries are authorized via the HTTP Referer (sic) header (N.B. in order to prevent theft of service by third parties via header spoofing, only a limited number of Referer (sic)-authorized queries are accepted per IP address). Server-side queries are authenticated via an API-key URL parameter.
In order to promote service availability even in the event of a data center-wide disruption, two API servers are provided, situated in geographically distinct data centers. Requests may be directed to either server. No appreciable difference in performance or behavior should be expected. Clients are expected to alternate API servers in the event of communication failure or persistent errors.
All resources are exposed according to the following URL structure:
https://{server}/{version}/path/to/resource
Required parameters:
| Name | Description | Value(s) |
|---|---|---|
| server | The server name. | api2.qasemail.qas.com |
| version | The API version. | v2 |
Clients must examine the HTTP status code of server replies before attempting to interpret their content. The following status codes are specifically defined, but clients should be prepared to interpret other status codes, such as might be generated by intermediate proxies or firewalls, as per RFC 2616:
| Status code | Interpretation |
|---|---|
| 200 OK | The request was well-formed and the reply contains the result. |
| 202 Accepted | The request was well-formed but the result is not yet available. |
| 400 Bad Request | The request was malformed and should not be retried without modification. The reply content will contain a description of the error. |
| 401 Unauthorized | No authorization credentials were supplied, they were invalid, or they were encoded incorrectly. Check your WWW-Authenticate header. |
| 429 Too Many Requests | Requests made to the API are rate-limited. This response code signifies that the rate-limit has been exceeded. |
| 500 Internal Server Error | An unexpected error occurred. The request may be retried (perhaps with an alternate server), but persistent failures should be reported. |
| 503 Service Unavailable | The server is temporarily overloaded and not accepting new requests. Requests should temporarily be directed to an alternate server. |
The default resource representation format is JSON; however, XML representations can be requested by specifying application-xml in the Accept header. Clients unable to modify headers may pass this value via an accept-header URI parameter, instead.
When validating server replies, clients should ensure that all expected fields are present. However, in order to accommodate intra-version additions to the API, any unexpected fields must be ignored. Clients must not rely on any undocumented fields.
GET is the only method allowed for this resource. Its relative path has the following structure:
/validity/{address}?timeout={timeout}
The parameters are as follows:
| Name | Description | Value | Required? |
|---|---|---|---|
| address | The email address to validate. | A percent-encoded email address. | Yes |
| timeout | The timeout, in seconds. | Integer (truncated to the range [3, 15]). | Yes |
| key | API key (required unless otherwise stated). | A unique API key. | Yes |
| verbose_output | Where to return verbose flags or not | True or False | Optional |
The representation (named validity, if XML) will contain the following fields:
| Name | Description | Value(s) |
|---|---|---|
| address | The email address. | A string (nominally an email address). |
| result | The validation result. | See Section A-2. |
The representation may also contain one or more of the following fields:
| Name | Description | Value(s) |
|---|---|---|
| role | Is this a nontechnical role account? | 'true' or not present. |
| full | Is the mailbox full? | 'true' or not present. |
| timeout | Was the query's timeout exhausted? | 'true' or not present. |
| retry | You may retry after this many seconds. | An integer or not present. |
| corrections | List of suggested corrections. | Array consisting of email addresses. |
| verbose_output | The verbose flag returned only if specified. | See Section A-4. |
Clients will receive a result of unknown for any queries not satisfied within the timeout period, starting from when the request is received, and ending when it is replied to, server-side.
Results of unknown or unreachable may occasionally be due to transient issues, such as DNS errors, mail exchanger misconfiguration, server rate-limiting (for real-time queries) or even internal errors. When there is any possibility of this being the case, the result field will be accompanied by a retry field, specifying how many seconds must be waited before retrying the query, if desired.
Zero or more corrections may be returned for a given email address. Corrections will be returned by the real-time endpoint as an array of email addresses, sorted by descending order of likelihood.
Corrections returned by real-time validation are not guaranteed to be verified. The Email Validation platform makes a best-effort to validate these suggested corrections without affecting response time. The system attempts to validate all suggested corrections simultaneously, removing any invalid addresses as they are identified. When the original address has been conclusively validated, the array of remaining corrections is returned.
To validate "fake-address@example.com", the client might GET the resource at:
https://api2.qasemail.qas.com/v2/validity/fake-address@example.com?timeout=5&key={API key}
and would receive the following representation:
`{ "address": "fake-address@example.com", "result": "undeliverable" }
To validate "fake address@gmal.com," the client might GET the resource at:
https://api2.qasemail.qas.com/v2/validity/fake%20address@gmal.com?timeout=5&key={API key}
the response would be in the form of:
'{ “address”: “fake address@gmal.com”,
“result”: “undeliverable”,
"corrections" : ["fakeaddress@gmail.com", "fakeaddress@gmal.com"] }
NOTE: the corrections shown above are purely for documentation purpose and may not reflect the behavior of the corrections module.
The Email Validation Platform is accessible via an FTP service for batch processing. Special folders (see Section C-4) and error-checking (see Section C-5) facilitate robust, fully automated integrations.
All files are transmitted via TLS (SSL) and the servers authenticated via 2048-bit X.509 digital certificates.
No client's files nor folders are visible to nor accessible by any other client.
To connect to the SFTP server, the following configuration must be used, along with your account username and password:
| Name | Description | Value(s) |
|---|---|---|
| Host | URL for the SFTP server. | sftp2.qasemail.qas.com |
| Port | Port to use for connections. | 22 |
The client has access to the following folders:
| Path | Description |
|---|---|
| incoming | Place files here to submit them for validation. |
| outgoing | Pick up completed files here. |
The client has the following filesystem permissions and restrictions:
- Can only upload files into the incoming folder.
- Cannot move/rename any files.
- May delete files from any folder.
- Cannot create, rename or remove any folders.
Uploaded files must be RFC 4180-compliant CSVs (cf. http://tools.ietf.org/html/rfc4180 ):
- Commas are used to separate fields.
- DOS/Windows-style newline (CR+LF) are used to terminate records.
- The last record may or may not be terminated.
- Double-quotation marks are used to quote fields.
- Double-quotation marks are used to escape double-quotation marks.
- Fields containing commas, newlines or double-quotation marks must be quoted.
- Otherwise, quoting is optional.
In addition to the above, a header row is required. The email-address column must be named email (case-insensitive). Additional columns may be included, and will be preserved in the output, but none of them may be named result or correction. Additional column names may be reserved, in the future.
ASCII-mode FTP converts newline sequences during transfer, so use binary mode!
Output files will adhere to the same format as used for input, except containing additional fields named result and correction (with values as described in Section B-8).
Unlike the real-time API, if more than one correction is suggested by the service, only the most likely correction will be returned. This correction has been validated, and is guaranteed to be a "verified" or "unknown" result.
To simplify parsing (e.g. for direct, MS-SQL bulk import ), every field will be quoted.
Verbose output is also available for Batch but needs to be enabled. Please contact Support for enabling on your account.
It is helpful to think of the FTP service as a state machine: Whichever folder a file is in reflects its current processing state.
Importantly, because a file is only in a single state at any given time, it is not necessary to poll every folder. Rather, having uploaded a file, one need only poll the incoming folder. When the file is no longer there, it will appear in the outgoing directory for download.
Improperly formatted files will are rejected from the system during the upload process. You will receive an email notification with details about what was wrong with the file. If malformed, manual intervention is required—something is wrong with how the file is formatted, and re-uploading it will not help. Review Section C-6 and ensure you have included a proper header row, are quoting any special characters (and properly escaping any quotes), are using the correct line terminators, and are using binary transfer mode.
When a file has completed processing, you will receive an email notification. The results may be retrieved from the outgoing folder, and will remain there for at least 30 days. After 30 days they may be deleted automatically by the FTP service due to our data retention policy. It is the client's responsibility to collect results before this time—and likewise to delete them, if so desired.
Before acting on the results, the client should always ensure they conform to the expected format, contain the expected records, and the results are within reasonable bounds.