flask-MailboxValidator 1.0.0

Email verification module for Flask 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.

MailboxValidator Flask Python Module

This Flask Python module provides an easy way to call the MailboxValidator API which validates if an email address is a valid one.

This module can be used in many types of projects such as:

• validating a user's email during sign up
• cleaning your mailing list prior to an email marketing campaign
• a form of fraud check

Installation

To install this module type the following:

pip install flask_MailboxValidator

Dependencies

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.

In order to use this module to validate email from form, WTForms and Flask-WTF need to be installed. Also, nose2 need to be installed in order to run the test file.

Usage for validate email from form

Note: WTForms and Flask-WTF must be installed before using this features.

1. Import Email Validation class from the package: from flask_MailboxValidator.SingleValidation import EmailValidation
2. Call the Email Validation in validator array along with your API key. email = TextField('Email:', validators=[validators.required(), EmailValidation(apikey='Your_API_Key')])

Usage for validating emails

import flask_MailboxValidator
from flask import Flask
from flask import jsonify

app = Flask(__name__)

mbv = flask_MailboxValidator.SingleValidation('PASTE_API_KEY_HERE')
results = mbv.ValidateEmail('[e-mail]')

@app.route('/')
def display_result():
	if results is None:
		return("Error connecting to API.\n")
	elif results['error_code'] == '':
		return (jsonify(results))
	else:
		return('error_message = ' + results['error_message'] + "\n")

Functions

SingleValidation(api_key)

Creates a new instance of the MailboxValidator object with the API key.

ValidateEmail(email_address)

Performs email validation on the supplied email address.

Result Fields

email_address

The input email address.

domain

The domain of the email address.

is_free

Whether the email address is from a free email provider like Gmail or Hotmail.

Return values: True, False

is_syntax

Whether the email address is syntactically correct.

Return values: True, False

is_domain

Whether the email address has a valid MX record in its DNS entries.

Return values: True, False, -   (- means not applicable)

is_smtp

Whether the mail servers specified in the MX records are responding to connections.

Return values: True, False, -   (- means not applicable)

is_verified

Whether the mail server confirms that the email address actually exist.

Return values: True, False, -   (- means not applicable)

is_server_down

Whether the mail server is currently down or unresponsive.

Return values: True, False, -   (- means not applicable)

is_greylisted

Whether the mail server employs greylisting where an email has to be sent a second time at a later time.

Return values: True, False, -   (- means not applicable)

is_disposable

Whether the email address is a temporary one from a disposable email provider.

Return values: True, False, -   (- means not applicable)

is_suppressed

Whether the email address is in our blacklist.

Return values: True, False, -   (- means not applicable)

is_role

Whether the email address is a role-based email address like [e-mail] or [e-mail].

Return values: True, False, -   (- means not applicable)

is_high_risk

Whether the email address contains high risk keywords.

Return values: True, False, -   (- means not applicable)

is_catchall

Whether the email address is a catch-all address.

Return values: True, False, Unknown, -   (- means not applicable)

mailboxvalidator_score

Email address reputation score.

Score > 0.70 means good; score > 0.40 means fair; score <= 0.40 means poor.

time_taken

The time taken to get the results in seconds.

status

Whether our system think the email address is valid based on all the previous fields.

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 disposable email provider

import flask_MailboxValidator
from flask import Flask
from flask import jsonify

app = Flask(__name__)

mbv = flask_MailboxValidator.SingleValidation('PASTE_API_KEY_HERE')
results = mbv.DisposableEmail('[e-mail]')

@app.route('/')
def display_result():
	if results is None:
		return("Error connecting to API.\n")
	elif results['error_code'] == '':
		return (jsonify(results))
	else:
		return('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

import flask_MailboxValidator
from flask import Flask
from flask import jsonify

app = Flask(__name__)

mbv = flask_MailboxValidator.SingleValidation('PASTE_API_KEY_HERE')
results = mbv.FreeEmail('[e-mail]')

@app.route('/')
def display_result():
	if results is None:
		return("Error connecting to API.\n")
	elif results['error_code'] == '':
		return (jsonify(results))
	else:
		return('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.

Test

To run the test file, you will first need to replace the 'PASTE_API_KEY_HERE' with your API key in the test file(Located at test directory). After that, run this command in terminal: python setup.py test

Errors

error_code	error_message
100	Missing parameter.
101	API key not found.
102	API key disabled.
103	API key expired.
104	Insufficient credits.
105	Unknown error.

Copyright

Copyright (C) 2018 by MailboxValidator.com, [e-mail]