Added disposable and free email APIs

Author: MailboxValidator

MailboxValidator/SingleValidation.py

@@ -18,3 +18,27 @@ def ValidateEmail(self, email):
             return json.loads(res.read())
         except:
             return None
+
+    def DisposableEmail(self, email):
+        p = { 'key': self.apikey, 'format': 'json', 'email': email }
+
+        try:
+            conn = http.client.HTTPConnection("api.mailboxvalidator.com")
+            conn.request("GET", "/v1/email/disposable?" + urllib.parse.urlencode(p))
+            res = conn.getresponse()
+            # print res.read()
+            return json.loads(res.read())
+        except:
+            return None
+
+    def FreeEmail(self, email):
+        p = { 'key': self.apikey, 'format': 'json', 'email': email }
+
+        try:
+            conn = http.client.HTTPConnection("api.mailboxvalidator.com")
+            conn.request("GET", "/v1/email/free?" + urllib.parse.urlencode(p))
+            res = conn.getresponse()
+            # print res.read()
+            return json.loads(res.read())
+        except:
+            return None

README.md

@@ -26,8 +26,8 @@ An API key is required for this module to function.
 Go to https://www.mailboxvalidator.com/plans#api to sign up for FREE API plan and you'll be given an API key.
 
 
-Usage
-=====
+Usage for validating emails
+===========================
 
 ```python
 import MailboxValidator
@@ -183,6 +183,121 @@ The error code if there is any error. See error table below.
 
 The error message if there is any error. See error table below.
 
+
+Usage for checking if an email is from a disposable email provider
+===================================================================
+
+```python
+import MailboxValidator
+	
+	mbv = MailboxValidator.SingleValidation('PASTE_API_KEY_HERE')
+	results = mbv.DisposableEmail('[email protected]')
+	
+	if results is None:
+		print("Error connecting to API.\n")
+	elif results['error_code'] == '':
+		print('email_address = ' + results['email_address'] + "\n")
+		print('is_disposable = ' + results['is_disposable'] + "\n")
+		print('credits_available = ' + str(results['credits_available']) + "\n")
+	else:
+		print('error_code = ' + results['error_code'] + "\n")
+		print('error_message = ' + results['error_message'] + "\n")
+```
+
+Functions
+=========
+
+### SingleValidation(api_key)
+
+Creates a new instance of the MailboxValidator object with the API key.
+
+### DisposableEmail(email_address)
+
+Check if the supplied email address is from a disposable email provider.
+
+Result Fields
+=============
+
+### email_address
+
+The input email address.
+
+### is_disposable
+
+Whether the email address is a temporary one from a disposable email provider.
+
+Return values: True, False
+
+### credits_available
+
+The number of credits left to perform validations.
+
+### error_code
+
+The error code if there is any error. See error table below.
+
+### error_message
+
+The error message if there is any error. See error table below.
+
+
+Usage for checking if an email is from a free email provider
+============================================================
+
+```python
+import MailboxValidator
+	
+	mbv = MailboxValidator.SingleValidation('PASTE_API_KEY_HERE')
+	results = mbv.FreeEmail('[email protected]')
+	
+	if results is None:
+		print("Error connecting to API.\n")
+	elif results['error_code'] == '':
+		print('email_address = ' + results['email_address'] + "\n")
+		print('is_free = ' + results['is_free'] + "\n")
+		print('credits_available = ' + str(results['credits_available']) + "\n")
+	else:
+		print('error_code = ' + results['error_code'] + "\n")
+		print('error_message = ' + results['error_message'] + "\n")
+```
+
+Functions
+=========
+
+### SingleValidation(api_key)
+
+Creates a new instance of the MailboxValidator object with the API key.
+
+### FreeEmail(email_address)
+
+Check if the supplied email address is from a free email provider.
+
+Result Fields
+=============
+
+### email_address
+
+The input email address.
+
+### is_free
+
+Whether the email address is from a free email provider like Gmail or Hotmail.
+
+Return values: True, False
+
+### credits_available
+
+The number of credits left to perform validations.
+
+### error_code
+
+The error code if there is any error. See error table below.
+
+### error_message
+
+The error message if there is any error. See error table below.
+
+
 Errors
 ======
 

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
 	name="MailboxValidator",
-	version="1.0.13",
+	version="1.1.0",
 	author="MailboxValidator.com",
 	author_email="[email protected]",
 	description="Email verification module for Python using MailboxValidator API. It validates if the email is valid, from a free provider, contains high-risk keywords, whether it\'s a catch-all address and so much more.",
@@ -21,4 +21,4 @@
 		"License :: OSI Approved :: MIT License",
 		"Operating System :: OS Independent",
 	),
-)
+)