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

NAME

Email::ExactTarget::SubscriberOperations - Collection of functions to manipulate arrayrefs of Subscriber objects.

VERSION

Version 1.6.0

SYNOPSIS

        # Create a new subscriber operations object
        my $subscriber_operations = $exact_target->subscriber_operations();
        
        my $subscribers;
        eval
        {
                $subscribers = $subscriber_operations->retrieve(
                        'email' => [ qw( test@test.invalid foo@bar.invalid ) ],
                );
        };
        warn "Retrieving the subscribers failed: $@" if $@;

METHODS

new()

Creates a new SubscriberOperations object, requires an Email::ExactTarget object to be passed as parameter.

        my $subscriber_operations = Email::ExactTarget::SubscriberOperations->new( $exact_target );

Note that this is not the recommended way of creating a SubscriberOperations object. If you are writing a script using this distribution, you should use instead:

        my $subscriber_operations = $exact_target->subscriber_operations();

exact_target()

Returns the main Exact Target object.

        my $exact_target = $subscriber_operations->exact_target();

create()

Creates a new subscriber in ExactTarget's database using the staged changes on the subscriber objects passed as parameter.

        $subscriber_operations->create(
                \@subscribers
        );

update_or_create()

Creates a new subscriber in ExactTarget's database using the staged changes on the subscriber objects passed as parameter. If the subscriber already exists in the database, updates it.

        $subscriber_operations->update_or_create(
                \@subscribers
        );

update()

Applies to ExactTarget's database any staged changes on the subscriber objects passed as parameter.

        $subscriber_operations->update(
                \@subscribers
        );

retrieve()

Retrieves from ExactTarget's database the subscribers corresponding to the unique identifiers passed as parameter.

        my $subscribers = $subscriber_operations->retrieve(
                'email' => [ $email1, $email2 ],
        );

pull_list_subscriptions()

Pulls from ExactTarget's database the list subscriptions for the arrayref of subscribers passed as parameter.

        # Pull list subscriptions.
        $subscriber_operations->pull_list_subscriptions(
                $subscribers
        );
        
        # Pull list subscriptions only for the specified lists.
        # This is helpful if you have a lot of legacy/historical lists you
        # don't actually sync with, as it cuts down on the number of results
        # and the time it takes to retrieve them.
        $subscriber_operations->pull_list_subscriptions(
                $subscribers,
                list_ids => \@list_ids,
        );

delete_permanently()

Deletes permanently the subscribers in the set passed as parameter from ExactTarget's database.

Note that this operation cannot be reversed. If you want to keep the subscribers but make sure emails are never sent to them, look into adding them to the "blacklist" list instead.

        my $all_subscribers_removed = $subscriber_operations->delete_permanently(
                \@subscribers
        );
        
        unless ( $all_subscribers_removed )
        {
                foreach my $subscriber ( @subscribers )
                {
                        my $errors = $subscriber->errors();
                        if ( defined( $errors ) )
                        {
                                # We failed to delete the subscriber.
                                print 'Failed to update subscriber ', $subscriber->id(), ": ", Dumper( $errors );
                        }
                        else
                        {
                                # Success.
                        }
                }
        }

INTERNAL FUNCTIONS

_update_create()

Internal. Updates or create a set of subscribers.

        my $batch_success = $subscriber_operations->_update_create(
                'subscribers' => \@subscriber,
                'soap_action' => 'Update',
                'soap_method' => 'UpdateRequest',
        );

        my $batch_success = $subscriber_operations->_update_create(
                'subscribers' => \@subscriber,
                'soap_action' => 'Create',
                'soap_method' => 'CreateRequest',
        );

Note $batch_success will be true only if all the elements have been updated successfully. When it is false, you should loop through @subscriber and use the errors() method on each object to find which one(s) failed.

_soap_format_lists()

Formats the lists subscription changes passed as a hashref for inclusion in the SOAP messages.

        my $soap_lists = $self->_soap_format_lists( $lists );

See http://wiki.memberlandingpages.com/API_References/Web_Service_Guide/_Technical_Articles/Managing_Subscribers_On_Lists.

_soap_format_attributes()

Formats the attributes passed as a hashref for inclusion in the SOAP messages.

        my $soap_attributes = $self->_soap_format_attributes( $attributes );

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::SubscriberOperations

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/