The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Email-ExactTarget-1.3.6
River stage zero No dependents
1 ++
/ Email::ExactTarget::Subscriber

NAME

Email::ExactTarget::Subscriber

VERSION

Version 1.3.6

SYNOPSIS

        # Create a new subscriber object.
        my $subscriber = Email::ExactTarget::Subscriber->new();
        
        # Set attributes.
        $subscriber->set(
                {
                        'First Name' => 'John',
                        'Last Name'  => 'Doe',
                }
        );
        
        # Get attributes.
        my $first_name = $subscriber->get('First Name');
        
        # ExactTarget's subscriber ID, if applicable.
        my $subscriber_id = $subscriber->id();

METHODS

new()

Creates a new Subscriber object.

        my $subscriber = Email::ExactTarget::Subscriber->new();

set()

Sets the attributes and values for the current subscriber object.

        $subscriber->set(
                {
                        'Email Address' => $email,
                        'First Name'    => $first_name,
                },
                'is_live' => $boolean, #default 0
        );

The is_live parameter allows specifying whether the data in the hashref are local only or if they are already synchronized with ExactTarget's database. By default, changes are considered local only and you will explicitely have to synchronize them using the functions of Email::ExactTarget::SubscriberOperations.

id()

Returns the Subscriber ID associated to the current Subscriber in Exact Target's database.

        $subscriber->id( 123456789 );

        my $subscriber_id = $subscriber->id();

This will return undef if the object hasn't loaded the subscriber information from the database, or if a new subscriber hasn't been committed to the database.

get()

When passed an attribute name as a parameter, retrieves the corresponding value:

        my $email = $subscriber->get( 'Email Address' );

Note that this will only show the live (retrieved from ExactTarget) values. If changes have been staged locally, this won't retrieve the new values until you synchronize them using one of the methods in Email::ExactTarget::SubscriberOperations.

#TODO: update documentation to reflect the is_live option.

get_attributes()

Retrieve a hashref containing all the attributes of the current object.

By default, it retrieves the live data (i.e., attributes synchronized with ExactTarget). If you want to retrieve the staged data, you can set is_live = 0> in the parameters.

        # Retrieve staged attributes (i.e., not synchronized yet with ExactTarget).
        my $attributes = $subscriber->get_attributes( 'is_live' => 0 );
        
        # Retrieve live attributes.
        my $attributes = $subscriber->get_attributes( 'is_live' => 1 );
        my $attributes = $subscriber->get_attributes();

apply_staged_attributes()

Moves the staged attribute changes onto the current object, effectively 'applying' the changes.

        $subscriber->apply_staged_attributes(
                [
                        'Email Address',
                        'First Name',
                ]
        ) || confess Dumper( $subscriber->errors() );

set_lists_status()

Stores the list IDs and corresponding subscription status.

        $subscriber->set_lists_status(
                {
                        '1234567' => 'Active',
                        '1234568' => 'Unsubscribed',
                },
                'is_live' => $boolean, #default 0
        );

The is_live parameter allows specifying whether the data in the hashref are local only or if they are already synchronized with ExactTarget's database. By default, changes are considered local only and you will explicitely have to synchronize them using the functions of Email::ExactTarget::SubscriberOperations.

'Active' and 'Unsubscribed' are the two valid statuses for list subscriptions.

get_lists_status ()

Returns the subscription status for the lists on the current object.

By default, it retrieves the live data (i.e., list subscriptions synchronized with ExactTarget). If you want to retrieve the staged data, you can set is_live = 0> in the parameters.

This function takes one mandatory parameter, which indicates whether you want the staged list information (lists subscribed to locally but not yet synchronized with ExactTarget) or the live list information (lists subscribed to in ExactTarget's database). The respective options are staged for the staged information, and live for the live information.

        # Retrieve staged attributes (i.e., not synchronized yet with ExactTarget).
        my $lists_status = $self->get_lists_status( 'is_live' => 0 );
        
        # Retrieve live attributes.
        my $lists_status = $self->get_lists_status( 'is_live' => 1 );
        my $lists_status = $self->get_lists_status();

apply_staged_lists_status()

Moves the staged list subscription changes onto the current object, effectively 'applying' the changes.

        $subscriber->apply_staged_lists_status(
                [
                        '1234567'
                        '1234568',
                ]
        ) || confess Dumper( $subscriber->errors() );

add_error()

Adds a new error message to the current object.

        $subscriber->add_error( 'Cannot update object.' ) || confess 'Failed to add error';

errors()

Returns the errors stored on the current object as an arrayref if there is any, otherwise returns undef.

        # Retrieve the errors.
        my $errors = $subscriber->errors();
        if ( defined( $errors ) )
        {
                print Dumper( $errors );
        }

        # Retrieve and remove the errors.
        my $errors = $subscriber->errors( reset => 1 );
        if ( defined( $errors ) )
        {
                print Dumper( $errors );
        }

flag_as_deleted_permanently()

Flags the subscriber as having been deleted in ExactTarget's database. Any subsequent operation on this object will be denied.

        $subscriber->flag_as_deleted_permanently();

is_deleted_permanently()

Returns a boolean indicating if the current object has been removed from ExactTarget's database.

        my $is_removed = $subscriber->is_deleted_permanently();

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

BUGS

Please report any bugs or feature requests to bug-email-exacttarget at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Email-ExactTarget. 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 Email::ExactTarget::Subscriber

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to ThinkGeek (http://www.thinkgeek.com/) and its corporate overlords at Geeknet (http://www.geek.net/), for footing the bill while I eat pizza and write code for them!

COPYRIGHT & LICENSE

Copyright 2009-2012 Guillaume Aubert.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/