/ 
Webservice-Sendy-API-0.5
/ Webservice::Sendy::API

NAME

Webservice::Sendy::API - Sendy's integration API Perl client and commandline utility

SYNOPSIS

use v5.10;
use strict;
use Webservice::Sendy::API qw//;

# constructor looks for default config file if not provided ..
my $sendy  = Webservice::Sendy::API->new;
my $brands = $sendy->get_brands;

foreach my $key (sort keys %$brands) {
  my $brand = $brands->$key;
  printf "%-3d  %s\n", $brand->id, $brand->name;
}

NOTE: This module requires a configuration file (defaults to $HOME/.sendy.ini) to be set up. See the ENVIRONMENT section below to learn more.

; defaults used for specified options
[defaults]
api_key=sOmekeyFromYourSendy
base_url=https://my.domain.tld/sendy
brand_id=1
list_id=mumdsQnpwnazscoOzKJ763Ow

; campaign information used for default brand_id 
[campaign]
from_name=List Sender Name
from_email=your-email-list@domain.tld
reply_to=some-other-reply-to@domain.tld

Save this file as $HOM/.sendy.ini, and you may start to use the sendy commandline utility.

DESCRIPTION

This is a full implementation of Sendy's Web API, version 6.1.2. Please alert author if this module has not been updated to support Sendy's latest API version.

Sendy is a commercial self-hosted email marketing application that integrates with Amazon SES (Simple Email Service) to send bulk emails at a low cost. It provides a user-friendly interface for creating campaigns, managing subscribers, and tracking email performance, making it a popular choice for businesses looking for an affordable, scalable email marketing solution. This module implements the Sendy API, which is based on simple HTTP POST. Use the API to integrate Sendy programmatically with your website or application. Some APIs may require the latest version of Sendy (currently version 6.1.2). Sendy requires a license to use.

Some sanity checking is done in the wrapper functions, but Sendy's API tend to do a good job of validation on the server side, and their error messages are pretty clear about what the issue is. In most cases, little additional validation is provided by this module and error messages are passed directly to the caller.

Sendy's API is not really RESTful because it doesn't use the HTTP status field. All calls return a 200 OK, therefore the HTTP::Tiny module that is used as the user agent in this module is forced to assume all calls are successful. In order to determine an error, the actual content of the response must be checked. This module does do that.

METHODS

create_campaign

Creates an email campaign; which can be saved as a draft, scheduled for sending, or sent immediately.

It is a FATAL error if title, subject, and html_text is not provided; the other fields required by the API can use defaults in the configuration file, listed after the check:

Required fields: from_name*, from_email*, reply_to*, title, subject, html_text, list_ids*, brand_id*, no_track_opens, no_track_clicks, send_campaign (* = uses defaults in .sendy.ini)

Optional fields: plain_text, segment_ids, exclude_list_ids, query_string, schedule_date_time, schedule_timezone

NOTE: Unless no_track_opens and no_track_clicks are set to 1 value, the campaign created will have them ON, respectively. In the sendy tool, this means that to turn off tracking, you'd need to supply the flags, --no_track_opens --no_track_clicks; in a similar way, the default behavior will always be to just create a draft. Therefore, to send the actual email campaign via this command, the send_campaign flag must be set to 1.

See more information about the call on Sendy's specification, https://sendy.co/api#create-send-campaigns.

subscribe

Subscribes an email address to a list.

Required fields: email, list_id

Optional fields: name, country, ipaddress, referrer, gdpr, silent, hp*

* hp is a honey pot field, if it is populated then the server side handler assumes it's been submitted by a bot, and will fail. So don't use it unless you're a super smat AI bot.

For a full description of the fields is available at https://sendy.co/api#subscribe.

unsubscribe

Unsubscribes an email address from a list, but keeps it in the list (marks it inactive).

Required fields: email, list_id

If not provided, list_id is pulled from the configuration file (if set).

This method automatically sets the field boolean to true; this is so the response if plain-text. There is no way to change this value without modifying the module. The alternative is to parse through a mess of HTML. This can me changed in future versions, but feedback is needed to know if this is useful.

For a full description of the fields is available at https://sendy.co/api#unsubscribe.

delete

Deletes an email address from a list.

Required fields: email, list_id

If not provided, list_id is pulled from the configuration file (if set).

This method automatically sets the field boolean to true; this is so the response if plain-text. There is no way to change this value without modifying the module. The alternative is to parse through a mess of HTML. This can me changed in future versions, but feedback is needed to know if this is useful.

For a full description of the fields is available at https://sendy.co/api#delete-subscriber.

get_subscriber_count

Returns the number of active subscribers that are in a list.

Required fields: list_id

If not provided, list_id is pulled from the configuration file (if set).

For a full description of the fields is available at https://sendy.co/api#subscriber-count.

get_subscriber_status

Returns the status of an email address with respect to a specific email list.

Required fields: email, list_id

If not provided, list_id is pulled from the configuration file (if set).

For a full description of the fields is available at https://sendy.co/api#subscription-status.

get_brands

No fields are required, brands are the highest level of entities available to list. All other calls require either a brand_id or list_id(s) to be specified.

Returns all brands. Brand Ids are numbers (1 through #brands).

For a full description of the fields is available at https://sendy.co/api#get-brands.

get_lists

Returns all lists based on a specified brand id. List Ids are alphanumeric hashes, therefore calls that operate using list specifier(s) do not also need to know the associated brand_id.

Required fields: brand_id

For a full description of the fields is available at https://sendy.co/api#get-brands.

sendy COMMANDLINE CLIENT

When installed, this module provides the commandline client, sendy. This script is both a real tool and a reference implementation for a useful client. It is meant for use on the commandline or in cron or shell scripts. It's not intended to be used inside of Perl scripts. It is recommended the library be used directly inside of the Perl scripts. Checkout the source code of sendy to see how to do it, if this documentation is not sufficient.

See the section on the ENVIRONMENT section below to learn how to set up the required configuration file.

Commands

brands

Returns list of brands by Id to STDOUT.

Usage,

sendy brands [--config alt-config.ini]
count

Returns count of the specified list to STDOUT.

Usage

sendy lists [--config alt-config.ini] --brand_id BRANDID
create

Creates an email campaign based on specified options. Status is returned via STDOUT.

By default full tracking is enabled. To turn off tracking, use the flags, --no_track_opens and --no_track_clicks.

To send right away, rather than just creating a draft; use the --send_campaign flag. There is currently no support to schedule the sending of a campaign at a later time. Please let me know if you need this ability. Otherwise it'll get implemented if and when I needed it.

Usage,

sendy create [--config alt-config.ini] --list_ids A,B,C,...
delete

Deletes the provided email from provided list Id, returns status to STDOUT.

Usage

sendy delete [--config alt-config.ini] --list_id LISTID --email
email@domain.tld
lists

Returns list of email lists for provided brand Id to STDOUT.

Usage

sendy lists [--config alt-config.ini] --brandid BRAND
status

Returns status of the provided email address to provided list Id, via STDOUT.

Usage

sendy status [--config alt-config.ini] --list_id LISTID --email
email@domain.tld
subscribe

Subscribes the provided email address to the provided list Id, result returned via STDOUT.

Usage

sendy subscribe [--config alt-config.ini] --list_id LISTID --email
email@domain.tld
unsubscribe

Unsubscribes the provided email address from the provided list Id, result returned via STDOUT.

Usage

sendy unsubscribe [--config alt-config.ini] --list_id LISTID --email
email@domain.tld

ENVIRONMENT

This module requires a configuration file, which may sound unusual. But it's the best way to manage API secrets. Please see below.

$HOME/.sendy.ini Configuration

A configuration file is required. The default file is $HOME/.sendy.ini. It is highly recommended that this file be chmod 600 (read only to the $USER. Note: Future versions of this module may enforce this file mode or automatically change permissions on the file.

; defaults used for specified options
[defaults]
api_key=sOmekeyFromYourSendy
base_url=https://my.domain.tld/sendy
brand_id=1
list_id=mumdsQnpwnazscoOzKJ763Ow

; campaign information used for default brand_id 
[campaign]
from_name=List Sender Name
from_email=your-email-list@domain.tld
reply_to=some-other-reply-to@domain.tld

AUTHOR

Brett Estrade <oodler@cpan.org>

Find out about this client and more Perl API clients at https://PerlClientDirectory.com.

BUGS

This module is meant to be used in production environments, but it still needs some maturing. Please report any bugs ASAP, to https://github.com/oodler577/p5-Webservice-Sendy-API/issues.

Please also report an issue if this module no longer supports Sendy's latest API version.

SEE ALSO

This module is meant to supercede Net::Sendy::API, which has not been updated since 2013.

LICENSE AND COPYRIGHT

Same as Perl/perl.