block-disposable-email.com provides an easy to understand JSON based service. JSON is a lightweight text-based open standard designed for human-readable data interchange. Please consider using the easyapi if you are looking for responses in JSON format.
API Key
In order to access this service you need a api key. You can find your personal api key at the management website.
URL Syntax and example
Syntax: http://check.block-disposable-email.com/api/json/{apikey}/{domain2check} Example: http://check.block-disposable-email.com/api/json/12345abc/block.setz.at
Additional parameters:
An additional parameter can be set to avoid mx checking (anyway, I recommend to check for the existence of a mx). The parameter is ment for people who already do a local mx check. Example: http://check.block-disposable-email.com/api/json/12345abc/block.setz.at/nomxcheck
Note: This parameter has to be in the right place (immediately after a slash after the domain name).
Response fields
Example: {“request_status”:”success”,”domain_status”:”block”,”domain_status_reason”:”block”, “domain_type”:”dea_provider”,”domain_is_handpicked”:”1″,”version”:”0.5″,”servertime”:”2012-04-11 23:18:00″,”comment”:”Blacklisted”,”server_id”:”setzling”}
Please note that the number of response parameters may change from time to time to tell you more about particular domains. So please check back occasionally to see if something useful has appeared.
- request_status:Describes if the server succeeded or found any problems (always in lower case).
- success: Everything fine, the request has been handled as expected and the checks will be performed.
- fail_key: Something is wrong with your api key. Please double-check, request a new one or contact me.
- fail_server: The server could not connect to the database or had some other problems.
- fail_input_domain: The domain you requested was sent in a wrong format, wg. without a dot, or with a dot at the end of the string, or any other mismatch. Since 2011-04-20 the real existence of the domain is checked additionally. If the domain does not exist even if it is syntactical correnct you will find the text “You submitted a non existing domain” in the comment field.
- domain_status:The simple answer if you should block or accept a domain (always in lower case).
- ok: Everything is fine with the domain. Accept your new subscriber.
- block: Something wrong. Better to block. The reason can be found in the next field.
- domain_status_reason: This field describes a bit better why your request has answered with block or ok – but it’s an acronym language, so it is easy to use in if statements (eg. if you want to accept subscribers with no mx records in their domain which are flagged as “block” in the domain status).
- ok: A whitelisted domain.
- block: A blacklisted domain.
- dea_provider: A blacklisted domain owned by a well known provider for temporary email addresses. Basically the same as block.
- check_unlist: Either a entry due to a known fake MX or flagged as to be checked up manually.
- check_list: One of our visitors flagged this domain as dea provider. Before we block it we have to check up manually.
- web_checked_ok: The crawler flagged this domain as “clean”. No dea services detected.
- web_checked_block: Our crawler identified this domain as a dea service.
- web_no_response: Our crawler tried hard but could not connect to the website of the domain. Flag it as OK so long.
- domain_without_mx: Only applicable if the input parameter “nomxcheck” is in use. It means that no mx record for the tested domain has been found.
- low_credits: If the number of remaining credits (paid credits and monthly free credits) is 0 this status will be sent. In this case the request_status is “success”, domain_status is “ok” due to legacy reasons. The given domains are not beeing checked.
- domain_type: Some of the domains are categorised. Currently the following values exists:
- dea_provider: provider of disposable email addresses, especially advertising with this feature
- free_web_email: like gmx.com, gmail.com
- company_email: commercial or privately used domain
- fun_domain: special alias domains of email providers
- unknown: literally unknown …
- suspect: no more details found but suspect (eg. domains formerly used for dea)
- no_valid_mx: means that there is no valid mx, leads to an useless email domain
- isp: service providers like Verizon
- parkingdomain: domains reserved but, often used to forward all inbound mails to a particular user – similar to disposable emails but used by the domain owner only
- free_hosting: providers of free servers, often used to cheat, so usually blocked
- [empty]: empty value, no classification found
- domain_is_handpicked: Shows if the requested domain has been checked manually in addition to the automatically performed tests. If you want to ensure that you limit the number of false positives as well as blocking real DEA domains only check for the combination of “handpicked = 1” and “domain_type = dea_provider”.
- version: Tells you the current version of the service. Sometimes time is changing things …
- servertime: The local time of the server in the moment of your request. If you feel any troubles and want to contact me please tell me this time so I can easier surf the logs.
- comment: A really human readable text regarding the domain_status_reason or other useful information.
- server_id: The internal name of the responding server.
How to use this data at your servers
PHP
JSON is a format that can easily been decoded to variables. One example of a complete email validation function written in php can be found here.
One more easy to understand code example:
<?php $domain = 'block.setz.at'; //testing only: replace dynamically by the domain of you subscribers $key = '12345abcapikey'; //please get your own valid api key $request = 'http://check.block-disposable-email.com/api/json/'.$key.'/'.$domain; $response = file_get_contents($request); $dea = json_decode($response); if ($dea->request_status == 'success') { if ($dea->domain_status == 'block' && $dea->domain_type == 'dea_provider' && $dea->domain_is_handpicked == 1) { // deny registration ... echo "Please do not use one-time email addresses ..."; } else { // ok, subscriber ot using known dea domain ... echo "Welcome ..."; } } // Do some other checks ... ?>
If you have or need some more examples please contact me.
Version Tracker JSON API
- 2013-14-01: deprecated – will be replaced by easyapi
- v 0.5 (2012-04-05): Added the “domain_is_handpicked” and “domain_type” attribute to limit the number of false positives. See description above. Please always check for this handpicked attribute!
- v 0.4 (2011-07-01): The service “block-disposable-email.com” turned from completely free to a “partly free” service (200 queries per month free, higher query amounts for prepaid users, see pricing). Due to this change new api responses have been added in case no more credits are available (see above).
- v 0.3 (2011-04-26): First mirror server activated. No change on protocol-level but two different responses for server_id (setzling=primary, mirror1_chicago = mirror).
- v 0.3 (2011-04-20): added new input parameter (nomxcheck, see example above); added new output value for domain_status_reason (domain_without_mx). Added test to evaluate if a domain exists (NS has to be found).
- v 0.2 (2011-04-15): added header information (Content-Type: application/json; charset=utf-8)
- v 0.1 (2011-04-13): Initial service started
(last change: Jan 13th, 2013)