The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-iContact-0.02
River stage zero No dependents
++
/ Net::iContact

NAME

Net::iContact - iContact API

VERSION

Version 0.02

SYNOPSIS

    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";
    }
    ...

ACCESSORS

The following functions take no arguments and return the property indicated in the name.

error( )

Returns the last error recieved, if any, as a hashref containing two keys: code, and message.

Example: print "Error code: " . $api->error->{'code'};

username( )

Returns the username that was supplied to the constructor.

password( )

Returns an md5 hash of the password that was supplied to the constructor.

api_key( )

Returns the api key.

secret( )

Returns the shared secret.

token( )

Returns the current token, if authenticated.

seq( )

Returns the current sequence number, if authenticated.

new( USERNAME, PASSWORD, APIKEY, SECRET, [DEBUG] )

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');

login( )

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"; }

API GET METHODS

For more details on the API calls implemented below, see the API documentation: http://app.icontact.com/icp/pub/api/doc/api.html

contacts( [FIELDS] )

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) { # ... }

contact( ID )

    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";

subscriptions( ID )

    ID: numeric contact ID

Returns a hashref of the given contact's subscriptions. See contacts

custom_fields( ID )

    ID: numeric contact ID

Returns a hashref of the given contact's custom fields. See contacts

campaigns( )

Returns an arrayref of all campaign IDs defined in the account, or a false value on error.

campaign( ID )

    ID: numeric campaign ID

Returns a hashref representing the campaign with the given ID. See campaigns.

lists( )

Returns an arrayref of all list IDs defined in the account, or a false value on error.

list( ID )

    ID: numeric list ID

Returns a hashref representing the list with the given ID. See lists.

stats( ID )

    ID: numeric message ID

Returns a hashref containing stats for the given message ID.

API PUT FUNCTIONS

For more details on the API calls implemented below, see the API documentation: http://app.icontact.com/icp/pub/api/doc/api.html

putmessage( SUBJECT, CAMPAIGN, TEXT_BODY, HTML_BODY )

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.

putcontact( CONTACT, [ID] )

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.

putsubscription( CONTACTID, LISTID, STATUS )

Update a contact's subscription.

    CONTACTID: contact ID to update
    LISTID: list ID
    STATUS: CONTACTID's subscription to LISTID (eg 'subscribed',
        'unsubscribed', 'deleted'...)

MISC FUNCTIONS

The following functions are intended for internal use, but may be useful for debugging purposes.

gen_sig( METHOD, ARGS )

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.

gen_url( METHOD, ARGS )

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 });

get( METHOD, ARGS )

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.

put( METHOD, ARGS, XML )

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.

AUTHOR

Ian Kilgore, <ian at icontact.com>

BUGS

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.

TODO

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.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::iContact

You can also look for information at:

ACKNOWLEDGEMENTS

SEE ALSO

http://app.icontact.com/icp/pub/api/doc/api.html

COPYRIGHT & LICENSE

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.