Skip to content

Latest commit

 

History

History
103 lines (73 loc) · 4.49 KB

README.md

File metadata and controls

103 lines (73 loc) · 4.49 KB
Raw

Kickbox Email Verification Service

Email Verification Library for Ruby

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.com 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 rubygems installed

$ gem install kickbox

Versions

Works with [ 1.9.* / 2.* ]

Usage

require "kickbox"

client   = Kickbox::Client.new('Your_API_Key_Here')
kickbox  = client.kickbox()
response = kickbox.verify("[email protected]")

verify returns a Kickbox::HttpClient::Response which has a body attribute which contains the deserialized JSON.

You can use it like this:

response.body['result'] #=> "deliverable"
response.body['reason'] #=>  "accepted_email"

Full response information is provided below

Options

timeout integer (optional) - Maximum time, in milliseconds, for the API to complete a verification request. Default: 6000.

# Example with options
response = kickbox.verify("[email protected]", { "timeout" => 60000 })

Response information

A successful API call responds with the following values:

  • result string - The verification result: deliverable, undeliverable, risky, unknown
  • reason string - The reason for the result. Possible reasons are:
    • invalid_email - Specified email is not a valid email address syntax
    • invalid_domain - Domain for email does not exist
    • rejected_email - Email address was rejected by the SMTP server, email address does not exist
    • accepted_email - Email address was accepted by the SMTP server
    • low_quality - Email address has quality issues that may make it a risky or low-value address
    • low_deliverability - Email address appears to be deliverable, but deliverability cannot be guaranteed
    • no_connect - Could not connect to SMTP server
    • timeout - SMTP session timed out
    • invalid_smtp - SMTP server returned an unexpected/invalid response
    • unavailable_smtp - SMTP server was unavailable to process our request
    • unexpected_error - An unexpected error has occurred
  • role true | false - true if the email address is a role address ([email protected], [email protected], etc)
  • free true | false - true if the email address uses a free email service like gmail.com or yahoo.com.
  • disposable true | false - true if the email address uses a disposable domain like trashmail.com or mailinator.com.
  • accept_all true | false - true if the email was accepted, but the domain appears to accept all emails addressed to that domain.
  • did_you_mean null | string - Returns a suggested email if a possible spelling error was detected. ([email protected] -> [email protected])
  • sendex float - A quality score of the provided email address ranging between 0 (no quality) and 1 (perfect quality). More information on the Sendex Score can be found here.
  • email string - Returns a normalized version of the provided email address. ([email protected] -> [email protected])
  • user string - The user (a.k.a local part) of the provided email address. ([email protected] -> bob)
  • domain string - The domain of the provided email address. ([email protected] -> example.com)
  • success true | false - true if the API request was successful (i.e., no authentication or unexpected errors occurred)

Response headers

Along with each response, the following HTTP headers are included:

  • X-Kickbox-Balance - Your remaining verification credit balance (Daily + On Demand).
  • X-Kickbox-Response-Time - The elapsed time (in milliseconds) it took Kickbox to process the request.

License

MIT

Bug Reports

Report here.

Need Help?

[email protected]