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
Example: my $contact = $api->contact($id); print $contact->{fname} .' '. $contact->{lname} .' <'. $contact->{email} . ">\n";
ID: numeric contact ID
Returns a hashref of the given contact's subscriptions. See contacts
ID: numeric contact ID
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.
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.
ID: numeric message ID
Returns a hashref containing stats for the given message ID.
For more details on the API calls implemented below, see the API documentation: http://app.icontact.com/icp/pub/api/doc/api.html
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:
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.
METHOD: scalar name of the method to be called
ARGS: a hashref of arguments to above method
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.
METHOD: scalar name of the method to be called
ARGS: a hashref of arguments to above method
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
Returns the raw XML recieved from the API.
Ian Kilgore, <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:
GET methods that are not provided at this time:
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.
You can find documentation for this module with the perldoc command.
perldoc Net::iContact
You can also look for information at:
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.
