csrest_subscribers.php

<?php
require_once dirname(__FILE__).'/class/base_classes.php';

/**
 * Class to access a subscribers resources from the create send API.
 * This class includes functions to add and remove subscribers ,
 * along with accessing statistics for a single subscriber
 * @author tobyb
 *
 */
class CS_REST_Subscribers extends CS_REST_Wrapper_Base {

    /**
     * The base route of the subscriber resource.
     * @var string
     * @access private
     */
    var $_subscribers_base_route;

    /**
     * Constructor.
     * @param $list_id string The list id to access (Ignored for create requests)
     * @param $api_key string Your api key (Ignored for get_apikey requests)
     * @param $protocol string The protocol to use for requests (http|https)
     * @param $debug_level int The level of debugging required CS_REST_LOG_NONE | CS_REST_LOG_ERROR | CS_REST_LOG_WARNING | CS_REST_LOG_VERBOSE
     * @param $host string The host to send API requests to. There is no need to change this
     * @param $log CS_REST_Log The logger to use. Used for dependency injection
     * @param $serialiser The serialiser to use. Used for dependency injection
     * @param $transport The transport to use. Used for dependency injection
     * @access public
     */
    function CS_REST_Subscribers (
    $list_id,
    $api_key,
    $protocol = 'https',
    $debug_level = CS_REST_LOG_NONE,
    $host = 'api.createsend.com',
    $log = NULL,
    $serialiser = NULL,
    $transport = NULL) {
        	
        $this->CS_REST_Wrapper_Base($api_key, $protocol, $debug_level, $host, $log, $serialiser, $transport);
        $this->set_list_id($list_id);

    }

    /**
     * Change the list id used for calls after construction
     * @param $list_id
     * @access public
     */
    function set_list_id($list_id) {
        $this->_subscribers_base_route = $this->_base_route.'subscribers/'.$list_id;
    }

    /**
     * Adds a new subscriber to the specified list
     * @param array $subscriber The subscriber details to use during creation.
     *     This array should be of the form
     *     array (
     *         'EmailAddress' => The new subscribers email address
     *         'Name' => The name of the new subscriber
     *         'CustomFields' => array(
     *             array(
     *                 'Key' => The custom fields personalisation tag
     *                 'Value' => The value for this subscriber
     *             )
     *         )
     *         'Resubscribe' => Whether we should resubscribe this subscriber if they already exist in the list
     *     )
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function add($subscriber) {
        return $this->post_request($this->_subscribers_base_route.'.json', $subscriber);
    }

    /**
     * Imports an array of subscribers into the current list
     * @param array $subscribers An array of subscribers to import.
     *     This array should be of the form
     *     array (
     *         array (
     *             'EmailAddress' => The new subscribers email address
     *             'Name' => The name of the new subscriber
     *             'CustomFields' => array(
     *                 array(
     *                     'Key' => The custom fields personalisation tag
     *                     'Value' => The value for this subscriber
     *                 )
     *             )
     *         )
     *     )
     * @param $resubscribe Whether we should resubscribe any existing subscribers
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'TotalUniqueEmailsSubmitted' => The number of unique emails submitted in the call
     *     'TotalExistingSubscribers' => The number of subscribers who already existed in the list
     *     'TotalNewSubscribers' => The number of new subscriptions to the list
     *     'DuplicateEmailsInSubmission' => array<string> The emails which appeared more than once in the batch
     *     'FailureDetails' => array (
     *         {
     *             'EmailAddress' => The email address which failed
     *             'Code' => The Create Send API Error code
     *             'Message' => The reason for the failure
     *         }
     *     )
     * }
     *
     */
    function import($subscribers, $resubscribe) {
        $subscribers = array(
		    'Resubscribe' => $resubscribe,
		    'Subscribers' => $subscribers
        );
        
        return $this->post_request($this->_subscribers_base_route.'/import.json', $subscribers);
    }

    /**
     * Gets a subscriber details, including custom fields
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'EmailAddress' => The subscriber email address
     *     'Name' => The subscribers name
     *     'Date' => The date the subscriber was added to the list
     *     'State' => The current state of the subscriber
     *     'CustomFields' => array(
     *         {
     *             'Key' => The custom fields personalisation tag
     *             'Value' => The custom field value for this subscriber
     *         }
     *     )
     * }
     */
    function get($email) {
        return $this->get_request($this->_subscribers_base_route.'.json?email='.urlencode($email));
    }

    /**
     * Gets the sending history to a specific subscriber
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * array(
     *     {
     *         ID => The id of the email which was sent
     *         Type => 'Campaign'
     *         Name => The name of the email
     *         Actions => array(
     *             {
     *                 Event => The type of action (Click, Open, Unsubscribe etc)
     *                 Date => The date the event occurred
     *                 IPAddress => The IP that the event originated from
     *                 Detail => Any available details about the event i.e the URL for clicks
     *             }
     *         )
     *     }
     * )
     */
    function get_history($email) {
        return $this->get_request($this->_subscribers_base_route.'/history.json?email='.urlencode($email));
    }

    /**
     * Unsubscribes the given subscriber from the current list
     * @param string $email The email address to unsubscribe
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function unsubscribe($email) {
        // We need to build the subscriber data structure.
        $email = array(
		    'EmailAddress' => $email 
        );
        
        return $this->post_request($this->_subscribers_base_route.'/unsubscribe.json', $email);
    }


}