csrest_campaigns.php

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

/**
 * Class to access a campaigns resources from the create send API.
 * This class includes functions to create and send campaigns,
 * along with accessing lists of campaign specific resources i.e reporting statistics
 * @author tobyb
 *
 */
class CS_REST_Campaigns extends CS_REST_Wrapper_Base {

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

    /**
     * Constructor.
     * @param $campaign_id string The campaign id to access (Ignored for create requests)
     * @param $auth_details array Authentication details to use for API calls.
     *        This array must take one of the following forms:
     *        If using OAuth to authenticate:
     *        array(
     *          'access_token' => 'your access token',
     *          'refresh_token' => 'your refresh token')
     *
     *        Or if using an API key:
     *        array('api_key' => 'your api key')
     * @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 __construct (
    $campaign_id,
    $auth_details,
    $protocol = 'https',
    $debug_level = CS_REST_LOG_NONE,
    $host = 'api.createsend.com',
    $log = NULL,
    $serialiser = NULL,
    $transport = NULL) {
        	
        parent::__construct($auth_details, $protocol, $debug_level, $host, $log, $serialiser, $transport);
        $this->set_campaign_id($campaign_id);
    }

    /**
     * Change the campaign id used for calls after construction
     * @param $campaign_id
     * @access public
     */
    function set_campaign_id($campaign_id) {
        $this->_campaigns_base_route = $this->_base_route.'campaigns/'.$campaign_id.'/';
    }

    /**
     * Creates a new campaign based on the provided campaign info.
     * At least on of the ListIDs and Segments parameters must be provided
     * @param string $client_id The client to create the campaign for
     * @param array $campaign_info The campaign information to use during creation.
     *     This array should be of the form
     *     array(
     *         'Subject' => string required The campaign subject
     *         'Name' => string required The campaign name
     *         'FromName' => string required The From name for the campaign
     *         'FromEmail' => string required The From address for the campaign
     *         'ReplyTo' => string required The Reply-To address for the campaign
     *         'HtmlUrl' => string required A url to download the campaign HTML from
     *         'TextUrl' => string optional A url to download the campaign
     *           text version from. If not provided, text content will be
     *           automatically generated from HTML content.
     *         'ListIDs' => array<string> optional An array of list ids to send the campaign to
     *         'SegmentIDs' => array<string> optional An array of segment ids to send the campaign to.
     *     )
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be the ID of the newly created campaign
     */
    function create($client_id, $campaign_info) {
        return $this->post_request($this->_base_route.'campaigns/'.$client_id.'.json', $campaign_info);
    }

    /**
     * Creates a new campaign from a template based on the info provided.
     * At least on of the ListIDs and Segments parameters must be provided
     * @param string $client_id The client to create the campaign for
     * @param array $campaign_info The campaign information to use during creation.
     *     This array should be of the form
     *     array(
     *         'Subject' => string required The campaign subject
     *         'Name' => string required The campaign name
     *         'FromName' => string required The From name for the campaign
     *         'FromEmail' => string required The From address for the campaign
     *         'ReplyTo' => string required The Reply-To address for the campaign
     *         'ListIDs' => array<string> optional An array of list ids to send the campaign to
     *         'SegmentIDs' => array<string> optional An array of segment ids to send the campaign to
     *         'TemplateID' => string required The ID of the template to use
     *         'TemplateContent' => array required The content which will be used to fill the editable areas of the template
     *     )
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be the ID of the newly created campaign
     */
    function create_from_template($client_id, $campaign_info) {
        return $this->post_request($this->_base_route.'campaigns/'.$client_id.'/fromtemplate.json', $campaign_info);
    }

    /**
     * Sends a preview of an existing campaign to the specified recipients.
     * @param array<string> $recipients The recipients to send the preview to.
     * @param string $personalize How to personalize the campaign content. Valid options are:
     *     'Random': Choose a random campaign recipient and use their personalisation data
     *     'Fallback': Use the fallback terms specified in the campaign content
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function send_preview($recipients, $personalize = 'Random') {
        $preview_data = array(
            'PreviewRecipients' => $recipients,
            'Personalize' => $personalize
        );

        return $this->post_request($this->_campaigns_base_route.'sendpreview.json', $preview_data);
    }

    /**
     * Sends an existing campaign based on the scheduling information provided
     * @param array $schedule The campaign scheduling information.
     *     This array should be of the form
     *     array (
     *        'ConfirmationEmail' => string required The email address to send a confirmation email to,
     *        'SendDate' => string required The date to send the campaign or 'immediately'.
     *                      The date should be in the format 'y-M-d'
     *     )
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function send($schedule) {
        return $this->post_request($this->_campaigns_base_route.'send.json', $schedule);
    }

    /**
     * Unschedules the campaign, moving it back into the drafts. If the campaign has been sent or is
     * in the process of sending, this api request will fail.
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function unschedule() {
        return $this->post_request($this->_campaigns_base_route.'unschedule.json', NULL);
    }

    /**
     * Deletes an existing campaign from the system
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function delete() {
        return $this->delete_request(trim($this->_campaigns_base_route, '/').'.json');
    }

    /**
     * Gets all email addresses on the current clients suppression list
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The suppressed email address
     *             'ListID' => The ID of the list this subscriber comes from
     *         }
     *     )
     * }
     */
    function get_recipients($page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'recipients.json', $page_number,
            $page_size, $order_field, $order_direction, '?');
    }

    /**
     * Gets all bounces recorded for a campaign
     * @param string $since The date to start getting bounces from
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email that bounced
     *             'ListID' => The ID of the list the subscriber was on
     *             'BounceType' => The type of bounce
     *             'Date' => The date the bounce message was received
     *             'Reason' => The reason for the bounce
     *         }
     *     )
     * }
     * )
     */
    function get_bounces($since = '', $page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'bounces.json?date='.urlencode($since),
            $page_number, $page_size, $order_field, $order_direction);
    }

    /**
     * Gets the lists a campaign was sent to
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'Lists' =>  array(
     *         {
     *             'ListID' => The list id
     *             'Name' => The list name
     *         }
     *     ),
     *     'Segments' => array(
     *         {
     *             'ListID' => The list id of the segment
     *             'SegmentID' => The id of the segment
     *             'Title' => The title of the segment
     *         }
     *     )
     * }
     */
    function get_lists_and_segments() {
        return $this->get_request($this->_campaigns_base_route.'listsandsegments.json');
    }

    /**
     * Gets a summary of all campaign reporting statistics
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'Recipients' => The total recipients of the campaign
     *     'TotalOpened' => The total number of opens recorded
     *     'Clicks' => The total number of recorded clicks
     *     'Unsubscribed' => The number of recipients who unsubscribed
     *     'Bounced' => The number of recipients who bounced
     *     'UniqueOpened' => The number of recipients who opened
     *     'WebVersionURL' => The url of the web version of the campaign
     *     'WebVersionTextURL' => The url of the web version of the text version of the campaign
     *     'WorldviewURL' => The public Worldview URL for the campaign
     *     'Forwards' => The number of times the campaign has been forwarded to a friend
     *     'Likes' => The number of times the campaign has been 'liked' on Facebook
     *     'Mentions' => The number of times the campaign has been tweeted about
     *     'SpamComplaints' => The number of recipients who marked the campaign as spam
     * }
     */
    function get_summary() {
        return $this->get_request($this->_campaigns_base_route.'summary.json');
    }

    /**
     * Gets the email clients that subscribers used to open the campaign
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * array(
     *     {
     *         Client => The email client name
     *         Version => The email client version
     *         Percentage => The percentage of subscribers who used this email client
     *         Subscribers => The actual number of subscribers who used this email client
     *     }
     * )
     */
    function get_email_client_usage() {
      return $this->get_request($this->_campaigns_base_route.'emailclientusage.json');
    }

    /**
     * Gets all opens recorded for a campaign since the provided date
     * @param string $since The date to start getting opens from
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email address of the subscriber who opened
     *             'ListID' => The list id of the list containing the subscriber
     *             'Date' => The date of the open
     *             'IPAddress' => The ip address where the open originated
     *             'Latitude' => The geocoded latitude from the IP address
     *             'Longitude' => The geocoded longitude from the IP address
     *             'City' => The geocoded city from the IP address
     *             'Region' => The geocoded region from the IP address
     *             'CountryCode' => The geocoded two letter country code from the IP address
     *             'CountryName' => The geocoded full country name from the IP address
     *         }
     *     )
     * }
     */
    function get_opens($since = '', $page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'opens.json?date='.urlencode($since),
            $page_number, $page_size, $order_field, $order_direction);
    }

    /**
     * Gets all clicks recorded for a campaign since the provided date
     * @param string $since The date to start getting clicks from
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email address of the subscriber who clicked
     *             'ListID' => The list id of the list containing the subscriber
     *             'Date' => The date of the click
     *             'IPAddress' => The ip address where the click originated
     *             'URL' => The url that the subscriber clicked on
     *             'Latitude' => The geocoded latitude from the IP address
     *             'Longitude' => The geocoded longitude from the IP address
     *             'City' => The geocoded city from the IP address
     *             'Region' => The geocoded region from the IP address
     *             'CountryCode' => The geocoded two letter country code from the IP address
     *             'CountryName' => The geocoded full country name from the IP address
     *         }
     *     )
     * }
     */
    function get_clicks($since = '', $page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'clicks.json?date='.urlencode($since),
            $page_number, $page_size, $order_field, $order_direction);
    }

    /**
     * Gets all unsubscribes recorded for a campaign since the provided date
     * @param string $since The date to start getting unsubscribes from
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email address of the subscriber who unsubscribed
     *             'ListID' => The list id of the list containing the subscriber
     *             'Date' => The date of the unsubscribe
     *             'IPAddress' => The ip address where the unsubscribe originated
     *         }
     *     )
     * }
     */
    function get_unsubscribes($since = '', $page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'unsubscribes.json?date='.urlencode($since),
            $page_number, $page_size, $order_field, $order_direction);
    }

    /**
     * Gets all spam complaints recorded for a campaign since the provided date
     * @param string $since The date to start getting spam complaints from
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email address of the subscriber who unsubscribed
     *             'ListID' => The list id of the list containing the subscriber
     *             'Date' => The date of the unsubscribe
     *         }
     *     )
     * }
     */
    function get_spam($since = '', $page_number = NULL, $page_size = NULL, $order_field = NULL,
        $order_direction = NULL) {
        return $this->get_request_paged($this->_campaigns_base_route.'spam.json?date='.urlencode($since),
            $page_number, $page_size, $order_field, $order_direction);
    }
}