235 lines
11 KiB
PHP
235 lines
11 KiB
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
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
if (!class_exists('CS_REST_Subscribers')) {
|
||
|
|
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 $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 string $protocol The protocol to use for requests (http|https)
|
||
|
|
* @param int $debug_level The level of debugging required CS_REST_LOG_NONE | CS_REST_LOG_ERROR | CS_REST_LOG_WARNING | CS_REST_LOG_VERBOSE
|
||
|
|
* @param string $host The host to send API requests to. There is no need to change this
|
||
|
|
* @param CS_REST_Log $log The logger to use. Used for dependency injection
|
||
|
|
* @param object|null $serialiser The serialiser to use. Used for dependency injection
|
||
|
|
* @param object|null $transport The transport to use. Used for dependency injection
|
||
|
|
* @access public
|
||
|
|
*/
|
||
|
|
function __construct (
|
||
|
|
$list_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_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
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
* 'ConsentToTrack' => Subscriber tracking preference ("yes", "no")
|
||
|
|
* 'Resubscribe' => Whether we should resubscribe this subscriber if they already exist in the list
|
||
|
|
* 'RestartSubscriptionBasedAutoResponders' => Whether we should restart subscription based auto responders which are sent when the subscriber first subscribes to a 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);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Updates an existing subscriber (email, name, state, or custom fields) in the specified list.
|
||
|
|
* The update is performed even for inactive subscribers, but will return an error in the event of the
|
||
|
|
* given email not existing in the list.
|
||
|
|
* @param string $email The email address of the susbcriber to be updated
|
||
|
|
* @param array $subscriber The subscriber details to use for the update. Empty parameters will remain unchanged
|
||
|
|
* This array should be of the form
|
||
|
|
* array (
|
||
|
|
* 'EmailAddress' => The new email address
|
||
|
|
* 'Name' => The name of the subscriber
|
||
|
|
* 'CustomFields' => array(
|
||
|
|
* array(
|
||
|
|
* 'Key' => The custom fields personalisation tag
|
||
|
|
* 'Value' => The value for this subscriber
|
||
|
|
* 'Clear' => true/false (pass true to remove this custom field. in the case of a [multi-option, select many] field, pass an option in the 'Value' field to clear that option or leave Value blank to remove all options)
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
* 'ConsentToTrack' => Subscriber tracking preference ("yes", "no")
|
||
|
|
* 'Resubscribe' => Whether we should resubscribe this subscriber if they already exist in the list
|
||
|
|
* 'RestartSubscriptionBasedAutoResponders' => Whether we should restart subscription based auto responders which are sent when the subscriber first subscribes to a list.
|
||
|
|
* )
|
||
|
|
* @access public
|
||
|
|
* @return CS_REST_Wrapper_Result A successful response will be empty
|
||
|
|
*/
|
||
|
|
function update($email, $subscriber) {
|
||
|
|
return $this->put_request($this->_subscribers_base_route.'.json?email='.urlencode($email), $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
|
||
|
|
* 'Clear' => true/false (pass true to remove this custom field. in the case of a [multi-option, select many] field, pass an option in the 'Value' field to clear that option or leave Value blank to remove all options)
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
* @param bool $resubscribe Whether we should resubscribe any existing subscribers
|
||
|
|
* @param bool $queueSubscriptionBasedAutoResponders By default, subscription based auto responders do not trigger during an import. Pass a value of true to override this behaviour
|
||
|
|
* @param bool $restartSubscriptionBasedAutoResponders By default, subscription based auto responders will not be restarted
|
||
|
|
* @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, $queueSubscriptionBasedAutoResponders = false, $restartSubscriptionBasedAutoResponders = false) {
|
||
|
|
$subscribers = array(
|
||
|
|
'Resubscribe' => $resubscribe,
|
||
|
|
'QueueSubscriptionBasedAutoResponders' => $queueSubscriptionBasedAutoResponders,
|
||
|
|
'Subscribers' => $subscribers,
|
||
|
|
'RestartSubscriptionBasedAutoresponders' => $restartSubscriptionBasedAutoResponders
|
||
|
|
);
|
||
|
|
|
||
|
|
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, $include_tracking_pref = NULL) {
|
||
|
|
return $this->get_request($this->_subscribers_base_route.'.json?email='.urlencode($email), $include_tracking_pref);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* deletes the given subscriber from the current list
|
||
|
|
* @param string $email The email address to delete
|
||
|
|
* @access public
|
||
|
|
* @return CS_REST_Wrapper_Result A successful response will be empty
|
||
|
|
*/
|
||
|
|
function delete($email) {
|
||
|
|
return $this->delete_request($this->_subscribers_base_route.'.json?email='.urlencode($email));
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|