A [Kickbox] (https://kickbox.io/) API client written in Elixir.
The package can be installed as:
- 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
```
- Ensure kickbox is started before your application:
```elixir
def application do
[applications: [:kickbox]]
end
```
- 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"
```
You call Kickbox.verify/2
with an email and an optional keyword list to query
the kickbox service.
# Just verify email
Kickbox.verify("[email protected]")
# Verify email specifying a max timeout of 9 seconds
Kickbox.verify("[email protected]", 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("[email protected]")
verification.valid?
# false
verification.reason
# invalid_domain
See Vertication struct for more information.
The valid options
are:
api_key
: Your Kickbox API key. It can also be configured using theKICKBOX_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).
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 ([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)
- valid? true | false - true if the email address is
deliverable
(i.e.,result
key has a value ofdeliverable
).
You can see all the latest documentation and a more complete explanation at Kickbox' API Documentation.