README

Email Verification Library for Symfony

Kickbox determines if an email address is not only valid, but associated with a actual user. Uses include:

• Preventing users from creating accounts on your applications using fake, misspelled, or throw-away email addresses.
• Reducing bounces by removing old, invalid, and low quality email addresses from your mailing lists.
• Saving money and projecting your reputation by only sending to real email users.

Getting Started

To begin, hop over to kickbox.io and create a free account. Once you've signed up and logged in, click on API Settings and then click Add API Key. Take note of the generated API Key - you'll need it to setup the client as explained below.

Installation

Make sure you have composer installed.

Add the following to your composer.json

$ php composer.phar require andi/kickbox-bundle

This package follows the PSR-4 convention names for its classes, which means you can easily integrate these classes loading in your own autoloader.

Register the bundle in app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        new Andi\KickBoxBundle\AndiKickBoxBundle(),
    );
}

In your config.yml, you must configure:

# Default configuration for extension with alias: "andi_kick_box"
andi_kick_box:

    # API key list.
    api_keys:             # Required
        toto:
            # The api key generated in kickbox.io.
            key: YOU_API_KEY       # Required
        tata:
            key: AN_OTHER_API_KEY
    # The default API name. If not set, the default value will be the first api name. 
    default_api_name: tata

    # The endpoint of the kickbox API.
    endpoint:             'https://api.kickbox.io/v2/verify'

Usage

Add the following code to our controller:

public function indexAction($email)
{
    $kickboxClient = $this->get('kickbox_client');
    $response      = $kickboxClient->verify($email);
}

We can also get a service name with a specific key defined in config.yml

Example:

	$kickboxClient = $this->get('kickbox_client');  // The default client. In our example : tata
	$kickboxClient = $this->get('kickbox_client.tata');
    $kickboxClient = $this->get('kickbox_client.toto');

To simply verify an email :

	$response = $kickboxClient->verify($email);

With a timeout :

   // Maximum time, in milliseconds, for the API to complete a verification request. Default value : 6000
   $response = $kickboxClient->verify($email, 6000);

An exception can be thrown by the api client if the HTTP status code is not 200 : Andi\KickBoxBundle\Exception\KickBoxApiException

Response

A successful API call responds with the following object:

    $response->getBalance();      // The remaining credit balance (Daily + On Demand).
    $response->getDomain();       // The domain of the provided email address.
    $response->getEmail();        // Returns a normalized version of the provided email address.
    $response->getReason();       // The reason for the result.
    $response->getResponseTime(); // The elapsed time (in milliseconds) it took Kickbox to process the request.
    $response->getResult();       // The verification result: deliverable, undeliverable, risky, unknown
    $response->getSuggestion();   // Returns a suggested email if a possible spelling error was detected.
    $response->getSendex();       // A quality score of the provided email address ranging between 0 (no quality) and 1 (perfect quality).
    $response->getUser();         // The user (a.k.a local part) of the provided email address. (bob@example.com -> bob).

    $response->isAcceptAll();     // If the email was accepted, but the domain appears to accept all emails addressed to that domain.
    $response->isDisposable();    // If the email address uses a disposable domain like trashmail.com or mailinator.com.
    $response->isFree();          // If the email address uses a free email service like gmail.com or yahoo.com.
    $response->isRole();          // If the email address is a role address
    $response->isSuccess();       // If the API request was successful.

All the Kickbox API is explained here : Using api API