Файл: campaign/csrest_campaigns.php
Строк: 706
<?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 CS_REST_Campaigns (
$campaign_id,
$auth_details,
$protocol = 'https',
$debug_level = CS_REST_LOG_NONE,
$host = 'api.createsend.com',
$log = NULL,
$serialiser = NULL,
$transport = NULL) {
$this->CS_REST_Wrapper_Base($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);
}
}