Kickbox

A [Kickbox] (https://kickbox.io/) API client written in Elixir.

Installation

The package can be installed as:

1. Add kickbox to your list of dependencies in mix.exs:

```elixir
def deps do
  # Get from hex
  [{:kickbox, "~> 0.1.0"}]
  # Or use the latest from master
  [{:kickbox, github: "pablo-co/kickbox-elixir"}]
end
```

2. Ensure kickbox is started before your application:

```elixir
def application do
  [applications: [:kickbox]]
end
```

3. Add your Kickbox API key to your config

> You can set the `KICKBOX_API_KEY` environment variable or can set it
> manually:

```elixir
# In your configuration file:
#  * General configuration: config/config.exs
#  * Recommended production only: config/prod.exs

config :kickbox, :kickbox_api_key, api_key: "my_api_key"
```

Verifying emails

You call Kickbox.verify/2 with an email and an optional keyword list to query the kickbox service.

# Just verify email
Kickbox.verify("some_email@email.com")

# Verify email specifying a max timeout of 9 seconds
Kickbox.verify("some_email@email.com", timeout: 9000)

# In general
Kickbox.verify(email_string, options)

You can then check the Kickbox.Verification struct for information regarding the queried email.

verification = Kickbox.verify("some_email@email.com")

verification.valid?
# false

verification.reason
# invalid_domain

See Vertication struct for more information.

Options

The valid options are:

• api_key: Your Kickbox API key. It can also be configured using the KICKBOX_API_KEY environment variable or through a configuration file (see step 3).
• timeout: Maximum time, in milliseconds, for the API to complete a verification request (default 6000).

options is a keyword list which gets converted to URL params, thus you can use any key/value you want (Note: These should be valid API params or they might get ignored by Kickbox).

Verification struct

Kickbox.verify/2 returns a Kickbox.Verification struct which contains information regarding the verification of the email.

• 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 (postmaster@example.com, support@example.com, 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. (bill.lumbergh@gamil.com -> bill.lumbergh@gmail.com)
• 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. (BoB@example.com -> bob@example.com)
• user string - The user (a.k.a local part) of the provided email address. (bob@example.com -> bob)
• domain string - The domain of the provided email address. (bob@example.com -> example.com)
• success? true | false - true if the API request was successful (i.e., no authentication or unexpected errors occurred)
• valid? true | false - true if the email address is deliverable (i.e., result key has a value of deliverable).

You can see all the latest documentation and a more complete explanation at Kickbox' API Documentation.