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

NAME

Email::ExactTarget::Subscriber - Object representing ExactTarget subscribers.

VERSION

Version 1.6.2

SYNOPSIS

        # Create a new subscriber object.
        my $subscriber = Email::ExactTarget::Subscriber->new();

        # Set attributes.
        $subscriber->set_attributes(
                {
                        'First Name' => 'John',
                        'Last Name'  => 'Doe',
                }
        );

        # Get attributes.
        my $first_name = $subscriber->get_attribute('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();

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.

MANAGING ATTRIBUTES

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 to 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();

get_attribute()

Retrieve the value corresponding to the attribute name passed as first parameter.

        # Retrieve staged (non-synchronized with ExactTarget) attribute named
        # 'Email Address'.
        my $staged_email_address = $subscriber->get_attribute(
                'Email Address',
                is_live => 0,
        );

        # If you've retrieved the subscriber object from ExactTarget, this
        # retrieves the live attribute that was returned by the webservice.
        my $live_email_address = $subscriber->get_attribute(
                'Email Address',
                is_live => 1,
        );

set_attributes()

Sets the attributes and values for the current subscriber object.

        $subscriber->set_attributes(
                {
                        '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.

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

MANAGING 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 to 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();

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.

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

MANAGING PROPERTIES

get_properties()

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

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

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

        # Retrieve live properties.
        my $properties = $subscriber->get_properties( 'is_live' => 1 );
        my $properties = $subscriber->get_properties();

get_property()

Retrieve the value corresponding to the property name passed as first parameter.

        # Retrieve staged (non-synchronized with ExactTarget) property named
        # EmailTypePreference.
        my $staged_email_type_preference = $subscriber->get_property(
                'EmailTypePreference',
                is_live => 0,
        );

        # If you've retrieved the subscriber object from ExactTarget, this
        # retrieves the live property that was returned by the webservice.
        my $live_email_type_preference = $subscriber->get_property(
                'EmailTypePreference',
                is_live => 1,
        );

set_properties()

Sets the properties and corresponding values for the current subscriber object.

        $subscriber->set_properties(
                {
                        EmailTypePreference => 'Text',
                },
                '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.

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

MANAGING DELETED SUBSCRIBERS

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

DEPRECATED METHODS

get()

Please use get_attribute() instead.

set()

Please use set_attribute() instead.

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/Email-ExactTarget/issues/new. 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:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

COPYRIGHT & LICENSE

Copyright 2009-2014 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/