NAME

Net::Mailboxlayer - Implements mailboxlayer.com's REST API, which a simple REST API measuring email deliverability and quality.

SYNOPSIS

 use Net::Mailboxlayer;

 my $mailboxlayer = Net::Mailboxlayer->new(access_key => 'YOUR_ACCESS_KEY', email_address => 'support@apilayer.com');
 my $result = $mailboxlayer->check;

 $result->email;        # support@apilayer.com
 $result->did_you_mean; # ""
 $result->user;         # support
 $result->domain;       # apilayer.net
 $result->format_valid; # 1
 $result->mx_found;     # 1
 $result->smtp_check;   # 1
 $result->catch_all;    # undef
 $result->role;         # 1
 $result->disposable;   # 0
 $result->free;         # 0
 $result->score;        # 0.8

See Net::Mailboxlayer::Response for more details.

DESCRIPTION

This module is a simple wrapper for mailboxlayer.com's REST API.

USAGE

new

Creates a new Net::Mailboxlayer object. Minimum required options are access_key and email_address, which must be set before check is called.

 my $mailboxlayer = Net::Mailboxlayer->new(access_key => 'YOUR_ACCESS_KEY', email_address => 'support@apilayer.com');

• access_key (required)

  See also method access_key. You can get an API KEY from https://mailboxlayer.com when you created an account.

• email_address (required)

  See also method email_address. This is the email address you want to measure.

• endpoint (optional)

  See also method endpoint. The endpoint of the api call. Defaults to https://apilayer.net/api/check.

• smtp (optional)

  See also method smtp. Defaults to 1 (enabled).

  Enables the MX-Records and SMTP checks.

  Reasons to turn off SMTP Check:

  The mailboxlayer SMTP Check feature takes up around 75% of the API's entire response time. If you would like to skip SMTP and speed up the API response, you may turn it off by setting the API's smtp parameter to 0.

• format (optional)

  See also method format. Defaults to 0 (disabled).

  Causes the response from the api to be prettified. Use this only for debugging.

• callback (optional)

  See also method callback. Sets your preferred JSONP callback function. See the official docs for more information.

  Provided for completeness and who knows, you might have some use for it! Let me know if you do.

• catch_all (optional)

  See also method catch_all. Enables catch-all detection functionality on the recipient SMTP server. Defaults to 0 (disabled).

  This has a heavy impact on response time, so is disabled by default.

• user_agent_opts (optional)

  See also method user_agent_opts. Sets default options for construction of a LWP::UserAgent object. Takes a hashref.

  Example:

   my $mailboxlayer = Net::Mailboxlayer->new(
     access_key => 'YOUR_ACCESS_KEY',
     email_address => 'support@apilayer.com',
     user_agent_opts => {
       ssl_opts => {verify_hostname => 1},
       timeout => 10,
     },
   );

• user_agent

  See also method user_agent. This will allow you to override the default useragent LWP::UserAgent. The given value must be blessed and have a 'get' method.

• <json_decoder>

  See also method json_decoder. This will allow you to override the default json decoder JSON::MaybeXS, which itself defaults to Cpanel::JSON::XS. The given value must be blessed and have a 'decode' method.

access_key

Allows you to set/change the access_key that you optionally provide with new. You must provide it before calling check. API KEYS are provided when you setup an account with https://mailboxlayer.com.

 $mailboxlayer->access_key('YOUR_ACCESS_KEY');

email_address

Allows you to set/change the email_address to measure. It must be provided before calling check.

 $mailboxlayer->email_address('support@apilayer.com');

endpoint

Allows you to set/change the endpoint that you optionally provide with new. Must be set before calling check. Defaults to https://apilayer.net/api/check.

 $mailboxlayer->endpoint('http://apilayer.net/api/check'); # don't use SSL for the endpoint
 $mailboxlayer->endpoint('https://apilayer.net/api/check'); # use SSL for the endpoint

smtp

Enables/disables the MX-Records and SMTP checks. Defaults to 1 (emabled).

 $mailboxlayer->smtp(0); # disable
 $mailboxlayer->smtp(1); # enable

Reasons to turn off SMTP Check:

The mailboxlayer SMTP Check feature takes up around 75% of the API's entire response time. If you would like to skip SMTP and speed up the API response, you may turn it off by setting the API's smtp parameter to 0.

format

Prettifies the JSON that is provided to Net::Mailboxlayer::Response. Use this only for debugging.

 $mailboxlayer->format(0); # disable
 $mailboxlayer->format(1); # enable

callback

Sets the preferred JSONP callback function. See the official docs (https://mailboxlayer.com/documentation) for more information. Provided for completeness.

catch_all

Enables catch-all detection on the recipient SMTP server. Defaults to 0 (disabled);

 $mailboxlayer->catch_all(0); # disable
 $mailboxlayer->catch_all(1); # enable

Note that as of 2016-08-12 this functionality is disabled for free accounts and will return an error if you enable it.

user_agent_opts

Sets default options for construction of a LWP::UserAgent object. Takes a hashref.

 $mailboxlayer->user_agent_opts({
  ssl_opts => {verify_hostname => 1},
  timeout => 10,
 });

The above tells LWP::UserAgent to verify ssl hostnames and sets the timeout to 10 seconds. See the LWP::UserAgent docs for more information and options.

user_agent

This will override the default LWP::UserAgent completely. Perhaps you want to construct your own, or you want to use an alternative module such as HTTP::Tiny.

 my $http = HTTP::Tiny->new(%attributes);
 $mailboxlayer->user_agent($http);

The only restriction is that you pass a blessed object that has a 'get' method.

json_decoder

This will override the default JSON::MaybeXS module. If you want to use JSON::XS instead, this would allow you.

 my $json = JSON::XS->new;
 $mailboxlayer->json_decoder($json);

The only restriction is that you pass a blessed ovject that has a 'decode' method.

check

Make the api call to measure the email_address.

This method will return either a Net::Mailboxlayer::Response object on success or a Net::Mailboxlayer::Error when an error occurs.

You can call $result->has_error to determine if there was an error or not.

 my $result = $mailboxlayer->check;
 if ($result->has_error)
 {
   # $result is a F<Net::Mailboxlayer::Error> object.
   print "There was an error: ". $result->info . "\n";
 }
 else
 {
   # $result is a F<Net::Mailboxlayer::Response> object.
   $result->score;
 }

AUTHOR

Tom Heady <cpan@punch.net>

COPYRIGHT & LICENSE

Copyright 2016 Tom Heady.

This program is free software; you can redistribute it and/or modify it under the terms of either:

• the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

• the Artistic License.

cpanm Net::Mailboxlayer

perl -MCPAN -e shell
install Net::Mailboxlayer