PHP Email Validation Tutorial using the MailboxValidator API

By Haseeb Ahmad Basil

zocuxtech.com

<email contact>

What is MailboxValidator?

MailboxValidator is an email validation API which can be used to check email lists to identify invalid or probably incorrect email addresses.

MailboxValidator uses SMTP checks and syntax based checks to identify the invalid email addresses. It also offers an API service which can be used for validating a single email address dynamically.

The API can return results in either XML or JSON format. We will further discuss here how to use that API in PHP.

Why use an Email Validation API?

An email validation API can be used to get rid of invalid email addresses from an email list, which in turn can reduce the bounce rate of your mailings.

Using an email validation API can increase email deliverability, reputation and effectiveness of email campaigns. Since sending emails to invalid addresses can damage your reputation, an email validation API can prevent that and reduce the risk of your email being blacklisted.

That will further help you against inconvenient users and increase the success of your mailing reaching actual real customers. Here we will discuss more about why MailboxValidator is a good choice for an email validation API.

Features

MailboxValidator comes with many great features. This article presents a few of the key features that can be of great help when validating emails. From simple syntax check, SMTP check and Greylist checker. Below are a few of the key features that are integrated in MailboxValidator.

Email Syntax Validation

The email syntax check can be used to detect if the syntax of the address is valid or not according to the current IETF standards. This feature helps to sort out the completely invalid email addresses, which in turn can reduce the number of other checks that will be needed to verify if the email is valid or not.

MX Record Checker

MX Records can be used to determine whether an SMTP server exists for the domain that the email address belongs to. This can help in sorting out the email addresses that doesn’t even have a valid mail server. Because if no mail server is receiving the emails what is the point of sending those.

MX Server Connection Checker

Once we have verified the MX records and know that an SMTP server exist for the email address, we will now establish a connection with that server to see whether it is accessible or not.

This is often accurate but in certain cases the mail server may still not accept messages to a given address. But there are other checks in place to make sure no false email address gets by.

Free or Disposable Email Provider Checker

This check is used to determine whether the provided email address belongs to some free or disposable email service provider.

Free email providers e.g. Gmail, Yahoo, etc. or Disposable email providers (DEA) like Mailinator, 10 minute mail or 20 minute mail, etc, should be skipped when sending out emails due to various reasons. DEA are rejected because they are temporary, anonymous and sometimes associated with fraudulent activities.

While sending emails to the Free Email Addresses is usually OK, it may be better for certain email campaigns to exclude these email addresses to reduce the bounce rate.

Single Validation API

MailboxValidator also provides the Single Validation API which can be used to validate a single email address immediately and returns the results in either JSON or XML. MailboxValidator provides wrappers for this API in 7 different programming languages.

How does it work?

Now the first check is to see if the email address has a valid syntax because if the syntax is invalid then performing other checks is useless.

Once the syntax is cleared, then comes the interesting part, the check to see if the domain of the address is valid and is the part before `@` a valid mailbox on that server.

This works on the server by checking if the domains exist and is it configured to accept emails, if it does, then the request to check mailbox is sent. This part is not verified by sending an email to the address but by sending a request directly to the mail server.

API Usage

Now comes the most important part of the article: the examples for the single validation API (SVA).

The Mailboxvalidator PHP Wrapper

In this part we will specifically use the PHP wrapper for SVA. It is provided by MailboxValidator and is available via composer. It can be installed using the following command:

    composer require mailboxvalidator/mailboxvalidator-php

This will add the following inside `composer.json`:

    {
        "require": {
            "mailboxvalidator/mailboxvalidator-php": "^1.0"
        }
    }

And it creates `mailboxvalidator\mailboxvalidator-php` path inside the vendor directory. This wrapper is a stand-alone library and has no dependencies.

Now, with this out of the way we can start with the actual code. Create an `index.php` in the same directory where you ran the `composer` command. And put the following code inside the file:

<?php
	include 'vendor/autoload.php';
	use MailboxValidator\SingleValidation;
	$validator = new SingleValidation( 'YOUR_API_KEY_HERE' );
	$results = $validator->ValidateEmail( 'example@example.com' );

Now in the above code, as you can see, first of all we include the composer's autoloader. Which autoloads the MailboxValidator library into our code and we can access that library using the appropriate namespace, which in this case is MailboxValidator. And in that namespace, is a class called `SingleValidation`. We’ll create an instance of that in the next line.

Now be sure to provide your API KEY in that line. You can get your API key from your Account's Dashboard on mailboxvalidator.com, but first you will have to apply for an API Plan.

MailboxValidator offers multiple API Plans, including a free plan, which offers 300 free API calls per month, and can be used on the low traffic sites.

Once you have provided the API key, your Validation system will be up and ready, you just have to provide an email and it will return the validation results instantly. From the above example if we would var_dump() the $results. We will get an output similar to this:

object(stdClass)[2]
  public 'email_address' => string 'example@example.com' (length=19)
  public 'domain' => string 'example.com' (length=11)
  public 'is_free' => string 'True' (length=4)
  public 'is_syntax' => string 'True' (length=4)
  public 'is_domain' => string 'False' (length=5)
  public 'is_smtp' => string '-' (length=1)
  public 'is_verified' => string '-' (length=1)
  public 'is_server_down' => string '-' (length=1)
  public 'is_greylisted' => string '-' (length=1)
  public 'is_disposable' => string 'True' (length=4)
  public 'is_suppressed' => string 'True' (length=4)
  public 'is_role' => string 'False' (length=5)
  public 'is_high_risk' => string 'False' (length=5)
  public 'is_catchall' => string 'Unknown' (length=7)
  public 'mailboxvalidator_score' => string '0.01' (length=4)
  public 'time_taken' => string '0.0428' (length=6)
  public 'status' => string 'False' (length=5)
  public 'credits_available' => int 279
  public 'error_code' => string '' (length=0)
  public 'error_message' => string '' (length=0)

Now from the above output, you can see that we have a result object that contains the validation properties for the email that came as a response from the MailboxValidator server.

An explanation of what all these properties represent can be found here. It is up to you to decide which of these validations you want to use, but keep in mind that some of these are high priority, meaning if they return false most of the others will be skipped.

These high priority parameters are:

1. is_syntax: If this call fails, all validations from `is_domain` to `is_catchall` will be skipped.
2. is_domain: If this call fails, all validations from is_smtp to is_greylisted will be skipped.  

So, to use the specific validations from this, you can do something like:

if($results->is_verified == 'True'
&& $results->is_greylisted != 'True')
{
    echo 'The provided email is valid';
}
else
{
    echo 'Email is invalid.';
}

The above code checks whether the mailbox exists on the server and is not grey listed. This is an example of how to use specific validation.

But if you want to use a more general validation you can use the `mailboxvalidator_score` field.

Explanation:

Mailboxvalidator_score: This is the score of the provided email address from 0.0 to 1.0. If it is > 0.7 it means the email is good. If it is < 0.7 and > 0.4 it means that it is fairly acceptable. But if it is ≤ 0.4 it means that is very poor.

Example:

if($results->mailboxvalidator_score > 0.7)
{
    echo 'This email is very good.';
}
elseif($results->mailboxvalidator_score < 0.7
&& $results->mailboxvalidator_score > 0.4)
{
    echo 'This email is OK';
}
else
{
    echo 'This email is invalid';
} 

In case the call doesn't work successfully, $results will either be a boolean false or have this property $results->error_code. Which you can easily verify with:

if ($results === false) 
{
    echo "Error connecting to API";
}
elseif(!empty($results->error_code)
{
    echo $results->error_message;
}

Now the thing with this wrapper is that it provides the response as an stdClass. But if you instead want the direct JSON or XML from the server you can make calls directly to the server for that.

Direct Connection

So, if instead of a PHP object you want the direct response in JSON or XML, you can make a direct call to API without using the provided wrapper. Here is a sample code that can be used:

$params['key'] = 'YOUR_API_KEY_HERE';
$params['format'] = 'json'; // Can be either 'xml' or 'json'
$params['email'] = 'test@gmail.com';
$query = http_build_query($params);
$result = file_get_contents( 'https://api.mailboxvalidator.com' . '/v1/validation/single?' . $query);
echo $result;

The result with JSON would be something like: 

{
    email_address: "test@gmail.com",
    domain: "gmail.com",
    is_free: "True",
    is_syntax: "True",
    is_domain: "True",
    is_smtp: "True",
    is_verified: "True",
    is_server_down: "False",
    is_greylisted: "False",
    is_disposable: "False",
    is_suppressed: "False",
    is_role: "False",
    is_high_risk: "True",
    is_catchall: "False",
    mailboxvalidator_score: "0.45",
    time_taken: "0.102",
    status: "False",
    credits_available: 258,
    error_code: "",
    error_message: ""
}

The result with XML would be something like:

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<email_address>test@gmail.com</email_address>
	<domain>gmail.com</domain>
	<is_free>True</is_free>
	<is_syntax>True</is_syntax>
	<is_domain>True</is_domain>
	<is_smtp>True</is_smtp>
	<is_verified>True</is_verified>
	<is_server_down>False</is_server_down>
	<is_greylisted>False</is_greylisted>
	<is_disposable>False</is_disposable>
	<is_suppressed>False</is_suppressed>
	<is_role>False</is_role>
	<is_high_risk>True</is_high_risk>
	<is_catchall>False</is_catchall>
	<mailboxvalidator_score>0.45</mailboxvalidator_score>
	<time_taken>0.0555</time_taken>
	<status>False</status>
	<credits_available>256</credits_available>
	<error_code></error_code>
	<error_message></error_message>
</response> 

Note: For https request, please make sure you have enabled php_openssl.dll extension in your php.ini. In case you have difficulty to modify the php.ini, you can always make the http request instead of https.

Is MailboxValidator Secure

Yes, MailboxValidator and its API are both very secure because MailboxValidator understands that your API requests may contain sensitive data. That is why all requests are sent over SSL and SHA256 with RSA encryption is used to make sure all requests are valid and completely secure.

Conclusion

As you can see from the examples and explanations above, it is very easy to setup and use MailboxValidator and its API.

From the installation of the wrapper to making a direct call to the server. Or how simply it detects the invalid emails, also the `mailboxvalidator_score` which makes it easier to validate an email using the simple scoring system.

Along with other validations which can be checked via simple if-else statements.