Validation levels


LEVEL-0 Base checks:

- invalid emails (example: john1980andnothing, ++--email--++@gmail.com);
- fabricated emails and typos (example: aaaaaaa@gmail.com);
- role accounts (example: abuse@... admin@...);
- short names at big ESPS (example: max@yahoo.com, bill@aol.com );
- aliases and tags (example: maxd+tag1@gmail.com, mybox-mytag@yahoo.com );
- disposable email addresses (example: a2bdd1@30minutemail.com);
- blacklisted problematic domains (example: billme1970@epomail.com);

Level-0 check takes 30-100 ms to complete.
Use it to block garbage registrations.


LEVEL-1 DNS records analyzing:

- all LEVEL-0 checks;
- missing A record (example: mygoodbox1@unexistingdomain.com);
- missing MX record (example: mygoodbox1@ca-ga.com);
- parked or problematic name server (example: mygoodbox4@guns.net);

Level-1 check may take up to 500 ms.

Use it to filter confirmation/opt-in notification;


LEVEL-2 Deep validation:

- all LEVEL-0 and level-1 checks;
- SMTP validation;
- Third party services validation;

Level-2 check may take up to 3 minutes.
By default it gets queued (you get QUEUED response).
Repeat API call later or wait for call-back to complete Level-0 validation.
Most complete validation level. Use it to scrub mailing list;


API methods


validate() - validate email OR queue for later check.

http://api.validatemyemail.com/v.php

parameters:

NAME DESCRIPTION
k API key
e email address
l validation level
w set to 1 to wait for long validation (levels 1 and 2)
x extra parameter should be passed in the call-back request

Method behaviour:

If validation result is available, API will respond with signal (BLOCK, PASS, etc.) and a sanitized email address.
You should replace user's email address (requested email) with the one returned by API.
Returned email may be empty if it doesnt pass basic syntax valiadtion, example "a@a@a.com" etc.
If validation result is not available, API will respond with signal Q (QEUEUD).
You can repeat the same check later to get result or wait for call-back request.
If you exsplictly specify level=0 you always get result immediately.
You cannot expect immidiete validation result for level 1-2


queue() - queue validation.

http://api.validatemyemail.com/q.php

parameters:

NAME DESCRIPTION
k API key
e email address
l validation level
x extra parameter should be passed in the call-back request

Method behaviour:

Method queues email for validation, and never return validation result.
You can call validate() method later to get result or wait for call-back
Method always respond with signal Q (QUEUED) and requested email address


report() - report email.

http://api.validatemyemail.com/r.php

parameters:

NAME DESCRIPTION
k API key
e email address
t report type:
    B = BOUNCE
    C = COMPLAINER
    O = EMAIL OPEN
    K = EMAIL CLICK
    F = EMAIL POSSIBLE FABRICATED
c SMTP code for bounce report
m SMTP message/details for bounce report

Method behaviour:

You can safely ignore API response for this method.


Call-back request


VME will perform call-back request, notifying about validation result.
In order to receive call-back, you need to provide call-back URL in the API setting in the Admin Control Panel (ACP)

Call-back request is HTTP POST request to specified call-back URL with following parameters:

NAME DESCRIPTION
E requested email
R raw API response
X extra parameter given into queue() or validate() method. For example user_ID.

End point should respond with plain text string "OK" as document body. Otherwise request will be marked as error and may be re-played.

It is recommended to release client as soon as possible (send "Connection: close header", flush bufer and use PHP ignore_user_abort(true) )


Raw API response


API response looks like this:

    Ba2bdd1@30minutemail.com
    ^\_____________________/
    |          |
    |          \- Returned email
    |
    \- SIGNAL

First character is signal code:

    P = PASS
    B = BLOCK
    D = DO NOT SEND
    X = CUSTOM X
    Y = CUSTOM Y
    Z = CUSTOM Z
    Q = QUEUED
    A = ACKNOWLEDGED
    E = ERROR

In case of error, error string will be in placed instead of returned email, example:

    EWrong Parameters
    ^\______________/
    |          |
    |          \- Error string
    |
    \- SIGNAL


API signals


API may respond with one of the following signal codes:

    P = PASS
    B = BLOCK
    D = DO NOT SEND
    X = CUSTOM X
    Y = CUSTOM Y
    Z = CUSTOM Z
    Q = QUEUED
    A = ACKNOWLEDGED
    E = ERROR

P = PASSED - All checks passed for given validation level.
B = BLOCKED (D, X, Y, Z) - One of the filters triggered. By default BLOCK signal will be sent on any trigger. You can change this to D, X, Y or X or P in the ACP.
Q = QUEUED - validation cannot be completed in the request. Either repeat validation later or wait for call-back
A = ACKNOWLEDGED - API server acknowledged request, no action should be taken.
E = ERROR - An error happened. Validation is not completed.