Guillaume Aubert > Email-ExactTarget-1.6.0 > Email::ExactTarget::Subscriber

Download:
Email-ExactTarget-1.6.0.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v1.6.0   Source   Latest Release: Email-ExactTarget-v1.6.2

NAME ^

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

VERSION ^

Version 1.6.0

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.

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-2013 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/

syntax highlighting: