Net::iContact - iContact API
Version 0.02
use Net::iContact; my $api = Net::iContact->new('user', 'pass', 'key', 'secret'); $api->login(); for my $list (keys %{$api->lists}) { print "ID: " . $list->{'id'} . "\n"; print "Name: " . $list->{'name'} . "\n"; } ...
The following functions take no arguments and return the property indicated in the name.
Returns the last error recieved, if any, as a hashref containing two keys: code, and message.
Example: print "Error code: " . $api->error->{'code'};
Returns the username that was supplied to the constructor.
Returns an md5 hash of the password that was supplied to the constructor.
Returns the api key.
Returns the shared secret.
Returns the current token, if authenticated.
Returns the current sequence number, if authenticated.
The constructor takes four scalar arguments and an optional fifth:
USERNAME: your iContact username PASSWORD: your iContact password APIKEY: the API key given to your application SECRET: the shared secret given to your application DEBUG: turns on debugging output. Optional, default is zero.
When DEBUG is true, Net::iContact will print the URLs it calls and the XML returned on STDERR.
Example: my $api = Net::iContact->new('user', 'pass', 'key', 'secret');
Logs into the API. Takes no arguments, returns true on success and false on error.
Example: my $ret = $api->login; unless ($ret) { print 'Error ' . $api->error->{'code'} . ': ' . $api->error->{'message'} . "\n"; }
For more details on the API calls implemented below, see the API documentation: http://app.icontact.com/icp/pub/api/doc/api.html
Search for contacts.
FIELDS: optional hash of search criteria
Returns an arrayref of all found contact IDs. If called with no arguments, returns all contacts in the account.
Example: my $contacts = $api->contacts(); # get all contacts ## get all contacts with @example.com email addresses and the first ## name 'Steve' $contacts = $api->contacts( 'email' => '*@example.com', 'fname' => 'Steve'); for my $id (@$contacts) { # ... }
ID: numeric contact ID
Returns a hashref representing the contact with the given ID. See contacts
contacts
Example: my $contact = $api->contact($id); print $contact->{fname} .' '. $contact->{lname} .' <'. $contact->{email} . ">\n";
Returns a hashref of the given contact's subscriptions. See contacts
Returns a hashref of the given contact's custom fields. See contacts
Returns an arrayref of all campaign IDs defined in the account, or a false value on error.
ID: numeric campaign ID
Returns a hashref representing the campaign with the given ID. See campaigns.
campaigns
Returns an arrayref of all list IDs defined in the account, or a false value on error.
ID: numeric list ID
Returns a hashref representing the list with the given ID. See lists.
lists
ID: numeric message ID
Returns a hashref containing stats for the given message ID.
Create a message.
SUBJECT: subject of the message CAMPAIGN: campaign to use TEXT_BODY: text part of the message HTML_BODY: html part of the message
Returns the ID of the created message on success, or a false value on failure.
Insert or update a contact's info.
CONTACT: hashref of contact info ID: optional contact ID
The CONTACT hashref has the following possible keys:
fname
lname
email
prefix
suffix
buisness
address1
address2
city
state
zip
phone
fax
Returns the ID of the contact on success, or a false value on failure.
Update a contact's subscription.
CONTACTID: contact ID to update LISTID: list ID STATUS: CONTACTID's subscription to LISTID (eg 'subscribed', 'unsubscribed', 'deleted'...)
The following functions are intended for internal use, but may be useful for debugging purposes.
Generates an api signature.
METHOD: scalar name of the method to be called ARGS: a hashref of arguments to above method
Returns the generated signature string.
Generates the URL to call, including the api_sig.
Returns the URL generated.
Example: my $url = $api->gen_url('auth/login/' . $api->username . '/' . $api->password, { 'api_key' => $api->api_key });
Makes an API GET call.
Returns the raw XML recieved from the API.
Makes an API PUT call.
METHOD: scalar name of the method to be called ARGS: hashref of arguments to above method XML: XML to PUT
Ian Kilgore, <ian at icontact.com>
<ian at icontact.com>
Need better documentation of return values (possibly documentation with Dumper output of the return values).
Net::iContact does not yet support authenticating to accounts with multiple client folders.
This module makes no attempt to deal with being rate-limited by the API.
PUT methods that are not provided at this time:
message/[message_id]/sending_info
GET methods that are not provided at this time:
message/[id]/stats/opens
message/[id]/stats/clicks
message/[id]/stats/bounces
message/[id]/stats/unsubscribes
message/[id]/stats/forwards
Please report any bugs or feature requests to bug-icontact-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-iContact. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-icontact-api at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Net::iContact
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Net-iContact
CPAN Ratings
http://cpanratings.perl.org/d/Net-iContact
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-iContact
Search CPAN
http://search.cpan.org/dist/Net-iContact
http://app.icontact.com/icp/pub/api/doc/api.html
Copyright 2007 iContact, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Net::iContact, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::iContact
CPAN shell
perl -MCPAN -e shell install Net::iContact
For more information on module installation, please visit the detailed CPAN module installation guide.