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

NAME

Email::ExactTarget - Interface to ExactTarget's API.

VERSION

Version 1.6.1

SYNOPSIS

This module allows you to interact with Exact Target, an Email Service Provider. It encapsulates all the communications with the API provided by Exact Target to offer a Perl interface for managing lists and subscribers amongst other features.

Please note that you will need to register with Exact Target first in order to obtain an API key and password, as well as agree with the Terms and Conditions for using the API.

        use Email::ExactTarget;
        
        # Create an object to communicate with Exact Target
        my $exact_target = Email::ExactTarget->new(
                'username'                => 'dummyusername',
                'password'                => 'dummypassword',
                'verbose'                 => 1,
                'unaccent'                => 1,
        );

METHODS

new()

Create a new Exact Target object that will be used as the interface with Exact Target's API.

        my $exact_target = Email::ExactTarget->new(
                'username'                => 'dummyusername',
                'password'                => 'dummypassword',
                'verbose'                 => 2,
                'unaccent'                => 1,
        );

Creates a new object to communicate with Exact Target.

'username' and 'password' are mandatory.

The verbose parameter is optional and defaults to not verbose.

The 'unaccent' parameter is optional and defaults to 0. See the documentation for unaccent() for more information.

subscriber_operations()

Create a new Email::ExactTarget::SubscriberOperations object, which will allow interacting with collections of Email::ExactTarget::Subscriber objects.

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

GETTERS / SETTERS

unaccent()

Exact Target charges a fee to allow accentuated characters to be passed through their API, and otherwise turns them into question marks (for example, "Jérôme" would become "J?r?me"). The alternative is to preemptively transform accentuated characters from the messages sent to Exact Target into their unaccentuated version("Jérôme" would thus become "Jerome"), which is free and degrades in an nicer way. To enable that automatic conversion to unaccentuated characters, set this to 1.

        $exact_target->unaccent( 1 );
        
        if ( $exact_target->unaccent() )
        {
                # [...]
        }

verbose()

Control the verbosity of the warnings in the code.

        $exact_target->verbose( 1 ); # turn on verbose information
        
        $exact_target->verbose( 0 ); # quiet now!

        warn 'Verbose' if $exact_target->verbose(); # getter-style

get_all_subscribers_list_id()

Discontinued, this method will be removed soon.

use_test_environment()

Return a boolean indicating whether the test environment is used in requests.

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

GENERAL WEBSERVICE INFORMATION

version_info()

Deprecated.

get_system_status()

See http://wiki.memberlandingpages.com/API_References/Web_Service_Guide/Methods/GetSystemStatus

Returns the system status information given by the webservice.

Return example:

        {
                'StatusCode'    => 'OK',
                'SystemStatus'  => 'OK',
                'StatusMessage' => 'System Status Retrieved',
        };

INTERNAL METHODS

soap_call()

Internal, formats the SOAP call with the arguments provided and checks the reply.

        my ( $error, $response_data ) = $exact_target->soap_call(
                'action'    => $method,
                'arguments' => $arguments,
        );

RUNNING TESTS

By default, only basic tests that do not require a connection to ExactTarget's platform are run in t/.

To run the developer tests, you will need to do the following:

  • Request access to the test environment from ExactTarget (recommended) unless you want to run the tests in your production environment (definitely NOT recommended).

  • Ask ExactTarget to enable the webservice access for you, if not already set up. It appears to be a customer-level property only ExactTarget can change.

  • In ExactTarget's interface, you will need to log in as an admin, then go to the "Admin" tab, "Account Settings > My Users". Then create a user with "API User" set to "Yes".

  • Go to the "Subscribers" tab, then "My Subscribers". If you look at the properties for the list named "All Subscribers", you will see a field named "ID". This is your "All Subscribers List ID", make a note of it.

  • Back to "My Subscribers", create at least two new lists and make a note of their IDs.

You can now create a file named ExactTargetConfig.pm in your own directory, with the following content:

        package ExactTargetConfig;
        
        # The arguments that will be passed to Email::ExactTarget->new() when
        # instantiating new objects during testing.
        sub new
        {
                return
                {
                        username                => 'username', # The username of the test account you created.
                        password                => 'password', # The password of the test account you created.
                        verbose                 => 0,
                        unaccent                => 1,
                        use_test_environment    => 1,
                };
        }
        
        # 'All Subscribers' is a special list in ExactTarget. If a user is
        # subscribed to a list but not the 'All Subscribers' list, the user
        # won't get any email.
        sub get_all_subscribers_list_id
        {
                # The ID of the 'All Subscribers' list that exists by default
                # in ExactTarget.
                return 00000;
        }
        
        # Tests cover adding/removing users from lists, this is an arrayref of
        # list IDs to use during those tests. Two list IDs are required.
        sub get_test_list_ids
        {
                return
                [
                        # The IDs of the test lists you created.
                        000000,
                        000000,
                ];
        }
        
        1;

You will then be able to run all the tests included in this distribution, after adding the path to ExactTargetConfig.pm to your library paths.

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

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

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/