Name
WWW::MyNewsletterBuilder - Perl implementation of the mynewsletterbuilder.com API
Synopsis
instantiate the module
use WWW::MyNewsletterBuilder;
my $mnb = WWW::MyNewsletterBuilder->new(
api_key => , # your key here
);quick test of server connection
print $mnb->HelloWorld('Perl Test');
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}get a list of campaigns and display their names
my $campaigns = $mnb->Campaigns( status => 'all' );
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}
foreach my $c (@$campaigns){
print $c->{name} . "\n";
}create a new campaign
my $cam_id = $mnb->CampaignCreate(
'perl test',
'perl test subject',
{
name => 'perl test from name',
email => 'robert@jbanetwork.com'
},
{
name => 'perl test reply name',
email => 'robert@jbanetwork.com'
},
'<a href="mynewsletterbuilder.com">html content</a>',
'text content',
);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}create a new subscriber list
my $list_id = $mnb->ListCreate(
'perl test',
'perl test list',
);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}add a subscriber
my $sub = $mnb->Subscribe(
{
email => 'robert@jbanetwork.com',
first_name => 'Robert',
last_name => 'Davis',
company_name => 'JBA Network',
phone_work => '8282320016,',
address_1 => '311 Montford Ave',
city => 'Asheville',
state => 'NC',
zip => '28801',
country => 'US',
'blah blah balh' => 'perl goes blah.',
},
[ $list_id ]
);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}schedule a campaign send
$mnb->CampaignSchedule(
$cam_id,
time(), # send it NOW
[ $list_id ],
);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}delete a subscriber
$mnb->SubscriberDelete($sub->{id});
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}delete a list
$mnb->ListDelete($list_id);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}delete a campaign
$mnb->CampaignDelete($cam_id);
if ($mnb->{errno}){
warn($mnb->{errstr});
#oh no there was an error i should do something about it
}Description
Methods
Instantiation And Setup
- $mnb = WWW::MyNewsletterBuilder->new( %options )
-
This method constructs a new
WWW::MyNewsletterBuilderobject and returns it. Key/value pair arguments may be provided to set up the initial state. The following options correspond to attribute methods described below:KEY DEFAULT ----------- -------------------- api_key undef (REQUIRED) username undef password undef timeout 300 secure 0 (1 will use ssl) no_validation 0 (1 will warn instead of die on invalid argument !!WARNING!!) ############################################# ### dev options... use at your own risk...### ############################################# _api_host 'api.mynewsletterbuilder.com' _api_version '1.0' _debug 0 (1 will print all kinds of stuff) - $mnb->Timeout( int $timeout )
-
sets timeout for results
Campaigns (Emails)
- $mnb->Campaigns( %filters )
-
returns an arrayref of hashrefs listing campaigns. Optional key/value pair argument allows you to filter results:
KEY OPTIONS ___________ ____________________ status draft, sent, scheduled, all(default) archived 1, 0 published 1, 0returns an arrayref of hashrefs in the following format:
KEY DESCRIPTION ___________ ____________________ id numeric id for campaign name campaign's name description campaign's description published 1 if campaign published 0 if not archived 1 if campaign archied 0 if not status status will be draft, sent or scheduled - $mnb->CampaignDetails( int $id )
-
requires a campaign id and returns a hashref containing the campaign's details with the following keys:
KEY DESCRIPTION ___________ ____________________ id name name for reply to reply_name name for reply to reply_email email address for reply to from_name name for from from_email email address for from subject email subject html email html body text email text body - $mnb->CampaignCreate( string $name, string $subject, \%from, \%reply, string $html, string $text, bool $link_tracking, bool $gat )
-
requires a whole bunch of stuff and returns the id of the newly created campaign. arguments:
string $name -- Internal campaign name string $subject -- Campaign subject line hashref $from -- keys are 'name' and 'email' hashref $reply -- keys are 'name' and 'email' (if empty $from is used) string $html -- HTML content for the campaign. string $text -- the text content for the campaign. (defaults to a stripped version of $html) bool $link_tracking -- 0 turn off link tracking 1(default) turns it on bool $gat -- 0(default) turns off Google Analytics Tracking 1 turns it on - $mnb->CampaignUpdate( int $id, \%details )
-
requires an int id and hashref details returns 1 if successful and 0 on failure. hashref format:
KEY DESCRIPTION ___________ ____________________ name Internal campaign name subject Campaign subject line from hashref with keys 'name' and 'email' reply hashref with keys are 'name' and 'email' (if empty $from is used) html HTML content for the campaign. text the text content for the campaign. link_tracking 0 turn off link tracking 1(default) turns it on gat 0(default) turns off Google Analytics Tracking 1 turns it on - $mnb->CampaignCopy( int $id, string $name )
-
takes an id and name copies an existing campaign identified by id and returns the new id. original name will be reused if name is ommitted.
- $mnb->CampaignDelete( int $id )
-
takes an id and deletes campaign idenified by that id. returns 1 on success and 0 on failure.
- $mnb->CampaignSchedule( int $id, string $when, \@lists, bool $smart, bool $confirmed )
-
schedules a Campaign for sending based on arguments:
int $id -- campaign id to send datetime $when -- date/time to send this can be in any format readable by PHP's strtotime() function and will be EST. array @lists -- flat array of list id's the campaign should go out to bool $smart -- 0(default) disables smart send 1 enables it. see http://help.mynewsletterbuilder.com/Help_Pop-up_for_Newsletter_Scheduler bool $confirmed -- 0(default) sends to all subscribers 1 sends to only confirmedreturns 0 on failure and 1 on success.
- $mnb->CampaignStats( int $id )
-
takes a campaign id and returns stats for that campaign. returned hahsref has the following keys:
KEY DESCRIPTION ___________ ____________________ id numeric id for campaign clicks number of clicks clicks_unique number of unique clicks forwards number of forwards forwards_unique number of unique forwards opens number of opens opens_unique number of unique opens recipients number of recipients bounces number of bounces delivered number delivered complaints number of complaints subscribes number of subscribes unsubscribes number of unsubscribes sent_on date and time campaign sent ('2010-03-04 01:30:47' EST) first_open date and time of first open ('2010-03-04 01:30:47' EST) last_open date and time of last open ('2010-03-04 01:30:47' EST) archived 1 if archived 0 if not - $mnb->CampaignRecipients( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber processed when campaign was sent to subscriber ('2010-03-04 01:30:47' EST) - $mnb->CampaignOpens( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who have opened the campaign in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber count number of opens first_open date and time subscriber first opened campaign ('2010-03-04 01:30:47' EST) last_open date and time subscriber last opened campaign ('2010-03-04 01:30:47' EST) - $mnb->CampaignBounces( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who bounced in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber processed when mnb processed bounce from subscriber ('2010-03-04 01:30:47' EST) - $mnb->CampaignClicks( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who clicked links in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber - $mnb->CampaignClickDetails( int $id, int $url_id, int $page, int $limit)
-
takes a campaign id, url id and optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who clicked links in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber count number of times subscriber clicked link url_id url id of link clicked - $mnb->CampaignSubscribes( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who subscribed based on this campaign in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber processed when subscriber was processed - $mnb->CampaignUnsubscribes( int $id, int $page, int $limit)
-
takes a campaign id, an optional page number and limit (for paging systems on large data sets) and returns an arrayref of hashrefs containing data about subscribers who unsubscribed in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of subscriber email email address of subscriber processed when subscriber was processed - $mnb->CampaignUrls( int $id )
-
takes a campaign id and returns an arrayref of hashrefs with link related data in the format:
KEY DESCRIPTION ___________ ____________________ id numeric id of url link FQDN for link unique number of unique clicks total number of total clicks title text within link (can include html including img tags)
Subscriber Lists
- $mnb->Lists()
-
returns an arrayref of hasrefs of subscriber lists with the following keys:
KEY DESCRIPTION ___________ ____________________ id numeric id for list name list name description list description visible 1 if visible 0 if not default 1 if default 0 if not subscribers number of subscribers in list - $mnb->ListDetails( int $id )
-
takes a list id and returns details about that list in a hashref with the following keys:
KEY DESCRIPTION ___________ ____________________ id list id name list name description list description visible 1 if list is visible 0 if not default 1 if list is a default selection on your subscription form subscribers total number of subscribers in the list - $mnb->ListCreate( string $name, string $description, bool $visible, bool $default )
-
takes several arguments, creates a new subscriber list and returns it's unique id. arguments:
string $name -- name for new list string $description -- description for new list bool $visible -- 1 if list is visible 0(default) if not bool $default -- 1 if list is default 0(default) if not - $mnb->ListUpdate( int $id, \%details )
-
takes an id and a hashref of details (only id is required though we won't actually do anything without something in the details hashref), updates the subscriber list identified by id and returns 1 on success and 0 on failure.
details hashref format:
KEY DESCRIPTION ___________ ____________________ name new name for list description new description for list visible 1 if list is visible 0(default) if not default 1 if list is default 0(default) if not - $mnb->ListDelete( int $id, bool $delete_subs )
-
deletes the list identified by id. if $delete_subs is 1 all subscribers in list are deleted as well. if delete_subs is 0(default) we don't touch subscribers. returns 1 on success and 0 on failure.
Subscribers
- $mnb->Subscribe( \%details, \@lists, bool $skip_opt_in, bool $update_existing )
-
sets up a single subscriber based on %details. if @lists is populated it OVERRIDES a current users current set of lists. if it is empty no changes are made to existing users. skip_opt_in is used to enable confirmation email (default is 0). update_existing is used to specify that you want %details to overrid an existing user's info. it will NOT be applied to lists. if lists is populated an existing user's lists WILL be overridden even with the update_existing flag set. it defaults to true.
%details is a hashref with the following format:
KEY DESCRIPTION ___________ ____________________ email subscriber email address(required) first_name subscriber first name middle_name subscriber middle name last_name subscriber last name full_name subscriber full name (yes this is a distinct field) company_name subscriber company name job_title subscribers job title phone_work subscriber work phone phone_home subscriber home phone address_1 first line of address address_2 second line of address address_3 third line of address city city of address state state of address zip postal code country country part of address custom field names custom field valuescustom fields can be set by using their full name as the key and their value as the value... again this can lead to keys with spaces.
Subscribe() returns a hashref with the following keys:
KEY DESCRIPTION ___________ ____________________ id subscriber's unique id email subscriber's uniqe email status status of subscription. possible values are new, updated, error, ignored status_msg contains text message about update... usually only used for errors - $mnb->SubscribeBatch( \@subscribers, \@lists, bool $skip_opt_in, bool $update_existing )
-
sets up multiple subscriber based on @subscribers which is an array of hashrefs. if @lists is populated it OVERRIDES any current users set of lists. if it is empty no changes are made to existing users. skip_opt_in is used to enable confirmation email (default is 0). update_existing is used to specify that you want %details to overrid an existing user's info. it will NOT be applied to lists. if lists is populated an existing user's lists WILL be overridden even with the update_existing flag set. it defaults to true.
@subscribers is an array of hashrefs with the following format:
KEY DESCRIPTION ___________ ____________________ email subscriber email address first_name subscriber first name middle_name subscriber middle name last_name subscriber last name company_name subscriber company name job_title subscribers job title phone_work subscriber work phone phone_home subscriber home phone address_1 first line of address address_2 second line of address address_3 third line of address city city of address state state of address zip postal code country country part of address custom field names custom field valuescustom fields can be set by using their full name as the key and their value as the value... again this can lead to keys with spaces.
SubscribeBatch() returns a hashref with the following keys:
KEY DESCRIPTION ___________ ____________________ meta contains a hashref with overview info described below subscribers contains an array of hashrefs described below. this will match the order of the @subscribers array you submittedthe meta key of the return from SubscribeBatch() contains a hashref with the following keys:
KEY DESCRIPTION ___________ ____________________ total total count of attempted subscribes success total count of successful subscribes errors total count of subscribes with errorsthe subscribers key of the return from SubscribeBatch() contains an array of hashrefs with the following keys:
KEY DESCRIPTION ___________ ____________________ id subscriber's unique id email subscriber's uniqe email status status of subscription. possible values are new, updated, error, ignored status_msg contains text message about update... usually only used for errors - $mnb->Subscribers( @statuses, @lists, int $page, int $limit )
-
takes arrays of statuses and list ids to filter by, an optional page number and limit (for paging systems on large data sets). returns an array of subscriber data.
options for statuses are active, unsubscribed, deleted.
return is a keyed array with the following keys:
KEY DESCRIPTION ___________ ____________________ id subscriber's unique id email subscriber's uniqe email status status of subscriber. possible values are active, unsubscribed or deleted - $mnb->SubscriberDetails( string $id_or_email )
-
takes an argument that can be either the unique id for the subscriber or an email address and returns a hashref of subscriber data in the following format:
KEY DESCRIPTION ___________ ____________________ id numeric id for subscriber email subscriber email address full_name subscriber full name first_name subscriber first name middle_name subscriber middle name last_name subscriber last name company_name subscriber company name job_title subscribers job title phone_work subscriber work phone phone_home subscriber home phone address_1 first line of address address_2 second line of address address_3 third line of address city city of address state state of address zip postal code country country part of address (may be improperly formatted) campaign_id if subscriber subscribed from a campaign it's id is here lists contains a flat array containing the lists the user is in last_confirmation_request last time we sent a confirmation to the user confirmed_date date subscriber confirmed confirmed_from ip address user confirmed from add_remove_date date subscriber status changed status current status possible values: active, unsubscribed, deleted, list_too_small add_method who last updated the user possible values: U - user added, S - added self, A - Admin added, C - added by complaint system, B - added by bounce management system confirmed status of confirmation (confirmed, unconfirmed, pending) custom field names custom field valuescustom fields will come back in this hashref with their names as keys and their values as the value. this means there is a possiblity that keys will have spaces in them. sorry.
- $mnb->SubscriberUpdate( string $id_or_email, \%details, \@lists )
-
takes an argument that can be either the unique id for the subscriber or an email address and updates a subscribers info and lists based on details hashref and lists arrayref. if @lists is empty NO CHANGES ARE MADE TO A USERS LISTS. use SubscriberDelete or SubscriberUnsubscribe to remove a subscriber from all lists.
%details is a hashref with the following format:
KEY DESCRIPTION ___________ ____________________ id numeric id for subscriber email subscriber email address full_name subscriber full name first_name subscriber first name middle_name subscriber middle name last_name subscriber last name company_name subscriber company name job_title subscribers job title phone_work subscriber work phone phone_home subscriber home phone address_1 first line of address address_2 second line of address address_3 third line of address city city of address state state of address zip postal code country country part of address custom field names custom field valuescustom fields can be set by using their full name as the key and their value as the value... again this can lead to keys with spaces.
- $mnb->SubscriberUnsubscribe( string $id_or_email )
-
takes an argument that can be either the unique id for the subscriber or an email address and permanantly removes that subscriber for the user identified by your api_key. this subscribers will NOT be able to be readded by SubscribeBatch().
returns 1 on success and 0 on failure.
- $mnb->SubscriberUnsubscribeBatch( \@ids_or_emails )
-
takes an argument that is an array containing either the unique ids for the subscriber or an email address and permanantly removes those subscribesr for the user identified by your api_key. these subscribers will NOT be able to be readded by SubscribeBatch().
returns 1 on success and 0 on failure.
- $mnb->SubscriberDelete( string $id_or_email )
-
takes an argument that can be either the unique id for the subscriber or an email address and removes that subscriber for the user identified by your api_key. this subscriber WILL be readded if their email address is re-submitted to Subscribe() or SubscribeBatch().
returns 1 on success and 0 on failure.
- $mnb->SubscriberDeleteBatch( \@ids_or_emails )
-
takes an argument that is an array containing either the unique id for subscribers or an email addresss and removes the subscribers for the user identified by your api_key. these subscribers WILL be readded if their email addresses are re-submitted to Subscribe() or SubscribeBatch().
returns 1 on success and 0 on failure.
Account Administration
- $mnb->AccountKeys( string $username, string $password, bool $disabled)
-
takes the user's username and password and returns data on available api keys. if $disabled(default 0) is 1 list will include disabled keys.
return is an array of hashrefs with the following keys:
KEY DESCRIPTION ___________ ____________________ id unique numeric id of key key unique key string created date key created expired date key expired or was disabled (null for valid key) - $mnb->AccountKeyCreate( string $username, string $password )
-
takes the user's username and password creates a key and returns data about created key. return is a hashref with the following keys:
KEY DESCRIPTION ___________ ____________________ id unique numeric id of key key unique key string create date key created expired date key expired or was disabled (null for valid key) - $mnb->AccountKeyEnable( string $username, string $password, string $id_or_key )
-
takes the user's username and password and an id or existing key it enables the referenced key and returns 1 on success and an error on failure.
- $mnb->AccountKeyDisable( string $username, string $password, string $id_or_key )
-
takes the user's username and password and an id or existing key it disables the referenced key and returns 1 on success and an error on failure.
Testing
Errors
By default we validate your data before sending to the server. If validation fails we issue die() with a relevant error message. You can force us to warn instead of dying by passing no_validation => 1 to new().
Server side errors will cause functions to return 0. They will also populate $mnb->{errno} and $mnb->{errstr}. You should probably check $mnb->{errno} after calling any function. Fatal errors within the underlying Frontier::Client module may be caught by the same mechinism that catches server side exceptions. You REALLY need to check for errors after ever call.
Requirements
Frontier::Client Data::Dumper
See Also
http://api.mynewsletterbuilder.com
Author
Robert Davis, robert@jbanetwork.com
Copyright And License
Copyright (C) 2010 by JBA Network (http://www.jbanetwork.com)
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.