Skip to content

Commit

Permalink
Merge pull request #72 from campaignmonitor/consent-to-track
Browse files Browse the repository at this point in the history
Updates to API - using v3.2 with ConsentToTrack updates
  • Loading branch information
taledo authored May 25, 2018
2 parents e4e0c4b + 07850e1 commit e343054
Show file tree
Hide file tree
Showing 18 changed files with 114 additions and 38 deletions.
7 changes: 7 additions & 0 deletions HISTORY.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# createsend-php history

## v6.0.0 - 23 May, 2018

* Upgrades to Createsend API v3.2 which includes new breaking changes
* Breaking: 'Consent to track' field is now mandatory for sending smart and classic transactionl emails
* Breaking: 'Consent to track' field is now mandatory when adding or updating subscribers
* Optional 'Include tracking preference' field when retrieving lists of subscribers

## v5.1.3 - 15th May, 2017

* Changed local API timeout from 10 sec to 20 sec
Expand Down
17 changes: 12 additions & 5 deletions class/base_classes.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
require_once dirname(__FILE__).'/transport.php';
require_once dirname(__FILE__).'/log.php';

defined('CS_REST_WRAPPER_VERSION') or define('CS_REST_WRAPPER_VERSION', '5.1.3');
defined('CS_REST_WRAPPER_VERSION') or define('CS_REST_WRAPPER_VERSION', '6.0.0');
defined('CS_HOST') or define('CS_HOST', 'api.createsend.com');
defined('CS_OAUTH_BASE_URI') or define('CS_OAUTH_BASE_URI', 'https://'.CS_HOST.'/oauth');
defined('CS_OAUTH_TOKEN_URI') or define('CS_OAUTH_TOKEN_URI', CS_OAUTH_BASE_URI.'/token');
Expand Down Expand Up @@ -146,7 +146,7 @@ function __construct(
$this->_log = is_null($log) ? new CS_REST_Log($debug_level) : $log;

$this->_protocol = $protocol;
$this->_base_route = $protocol.'://'.$host.'/api/v3.1/';
$this->_base_route = $protocol.'://'.$host.'/api/v3.2/';

$this->_log->log_message('Creating wrapper for '.$this->_base_route, get_class($this), CS_REST_LOG_VERBOSE);

Expand All @@ -171,6 +171,7 @@ function __construct(
'host' => $host,
'protocol' => $protocol
);

}

/**
Expand Down Expand Up @@ -230,7 +231,13 @@ function delete_request($route, $call_options = array()) {
return $this->_call($call_options, CS_REST_DELETE, $route);
}

function get_request($route, $call_options = array()) {
function get_request($route, $include_tracking_pref = NULL, $call_options = array()) {

if(isset($include_tracking_pref)
&& is_bool($include_tracking_pref)) {
$route .= '&includeTrackingPreference='.($include_tracking_pref ? "true" : "false");
}

return $this->_call($call_options, CS_REST_GET, $route);
}

Expand All @@ -247,7 +254,7 @@ function get_request_with_params($route, $params) {
return $this->get_request($route);
}

function get_request_paged($route, $page_number, $page_size, $order_field, $order_direction,
function get_request_paged($route, $page_number, $page_size, $order_field, $order_direction, $include_tracking_pref = NULL,
$join_char = '&') {
if(!is_null($page_number)) {
$route .= $join_char.'page='.$page_number;
Expand All @@ -269,7 +276,7 @@ function get_request_paged($route, $page_number, $page_size, $order_field, $orde
$join_char = '&';
}

return $this->get_request($route);
return $this->get_request($route, $include_tracking_pref);
}

/**
Expand Down
25 changes: 15 additions & 10 deletions csrest_lists.php
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ function get_segments() {
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -285,10 +286,10 @@ function get_segments() {
* }
*/
function get_active_subscribers($added_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_lists_base_route.'active.json?date='.urlencode($added_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction, $include_tracking_pref);
}

/**
Expand All @@ -298,6 +299,7 @@ function get_active_subscribers($added_since = '', $page_number = NULL,
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -325,10 +327,10 @@ function get_active_subscribers($added_since = '', $page_number = NULL,
* }
*/
function get_unconfirmed_subscribers($added_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_lists_base_route.'unconfirmed.json?date='.urlencode($added_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction, $include_tracking_pref);
}

/**
Expand All @@ -338,6 +340,7 @@ function get_unconfirmed_subscribers($added_since = '', $page_number = NULL,
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -365,10 +368,10 @@ function get_unconfirmed_subscribers($added_since = '', $page_number = NULL,
* }
*/
function get_bounced_subscribers($bounced_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_lists_base_route.'bounced.json?date='.urlencode($bounced_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction, $include_tracking_pref);
}

/**
Expand All @@ -378,6 +381,7 @@ function get_bounced_subscribers($bounced_since = '', $page_number = NULL,
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -405,10 +409,10 @@ function get_bounced_subscribers($bounced_since = '', $page_number = NULL,
* }
*/
function get_unsubscribed_subscribers($unsubscribed_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_lists_base_route.'unsubscribed.json?date='.urlencode($unsubscribed_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction,$include_tracking_pref);
}

/**
Expand All @@ -418,6 +422,7 @@ function get_unsubscribed_subscribers($unsubscribed_since = '', $page_number = N
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -445,10 +450,10 @@ function get_unsubscribed_subscribers($unsubscribed_since = '', $page_number = N
* }
*/
function get_deleted_subscribers($deleted_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_lists_base_route.'deleted.json?date='.urlencode($deleted_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction, $include_tracking_pref);
}

/**
Expand Down
5 changes: 3 additions & 2 deletions csrest_segments.php
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,7 @@ function clear_rules() {
* @param int $page_size The number of records per page
* @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
* @param string $order_direction The direction to order the record set ('ASC', 'DESC')
* @param boolean $include_tracking_pref Whether or not to return the ConsentToTrack value (true, false)
* @access public
* @return CS_REST_Wrapper_Result A successful response will be an object of the form
* {
Expand Down Expand Up @@ -199,10 +200,10 @@ function clear_rules() {
* }
*/
function get_subscribers($subscribed_since = '', $page_number = NULL,
$page_size = NULL, $order_field = NULL, $order_direction = NULL) {
$page_size = NULL, $order_field = NULL, $order_direction = NULL, $include_tracking_pref = NULL) {

return $this->get_request_paged($this->_segments_base_route.'/active.json?date='.urlencode($subscribed_since),
$page_number, $page_size, $order_field, $order_direction);
$page_number, $page_size, $order_field, $order_direction, $include_tracking_pref);
}
}
}
6 changes: 4 additions & 2 deletions csrest_subscribers.php
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ function set_list_id($list_id) {
* '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.
* )
Expand Down Expand Up @@ -102,6 +103,7 @@ function add($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.
* )
Expand Down Expand Up @@ -177,8 +179,8 @@ function import($subscribers, $resubscribe, $queueSubscriptionBasedAutoResponder
* )
* }
*/
function get($email) {
return $this->get_request($this->_subscribers_base_route.'.json?email='.urlencode($email));
function get($email, $include_tracking_pref = NULL) {
return $this->get_request($this->_subscribers_base_route.'.json?email='.urlencode($email), $include_tracking_pref);
}

/**
Expand Down
13 changes: 9 additions & 4 deletions csrest_transactional_classicemail.php
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,15 @@ function set_client($client_id) {
* )
* )
*/
function send($message, $group = NULL, $add_to_list_ID = NULL, $options = array()) {
$group_param = array( "Group" => $group);
$add_to_list_param = array( "AddRecipientsToListID" => $add_to_list_ID);
$data = array_merge($this->_client_id_param, $message, $group_param, $add_to_list_param, $options);
function send($message, $group = NULL, $consent_to_track, $add_to_list_ID = NULL, $options = array()) {
$all_params = array(
"Group" => $group,
"AddRecipientsToListID" => $add_to_list_ID,
"ConsentToTrack" => $consent_to_track
);
$data = array_merge(
$this->_client_id_param, $message, $all_params, $options
);
return $this->post_request($this->_base_route.'transactional/classicemail/send', $data);
}

Expand Down
7 changes: 5 additions & 2 deletions csrest_transactional_smartemail.php
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,11 @@ function get_list($options = array()) {
* )
* )
*/
function send($message, $add_to_list = true) {
$data = array_merge($message, array("AddRecipientsToList" => $add_to_list));
function send($message, $consent_to_track, $add_to_list = true) {
$data = array_merge($message, array(
"AddRecipientsToList" => $add_to_list,
"ConsentToTrack" => $consent_to_track
));
return $this->post_request($this->_smartemail_base_route . '/send.json', $data);
}

Expand Down
4 changes: 3 additions & 1 deletion samples/list/get_active_subscribers.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@
'refresh_token' => 'your refresh token');
$wrap = new CS_REST_Lists('List ID', $auth);

$result = $wrap->get_active_subscribers('Added since', 1, 50, 'email', 'asc');
//The 6th argument will return the tracking preference of the subscribers - 'ConsentToTrack'
$result = $wrap->get_active_subscribers('Added since', 1, 50, 'email', 'asc', true);

//$result = $wrap->get_active_subscribers(date('Y-m-d', strtotime('-30 days')),
// page number, page size, order by, order direction);

Expand Down
4 changes: 3 additions & 1 deletion samples/segment/get_subscribers.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@
'refresh_token' => 'your refresh token');
$wrap = new CS_REST_Segments('Segment ID', $auth);

$result = $wrap->get_subscribers('Added since', 1, 50, 'email', 'asc');
//The 6th argument will return the tracking preference of the subscribers - 'ConsentToTrack'
$result = $wrap->get_subscribers('Added since', 1, 50, 'email', 'asc', true);

//$result = $wrap->get_subscribers(date('Y-m-d', strtotime('-30 days')),
// page number, page size, order by, order description);

Expand Down
1 change: 1 addition & 0 deletions samples/subscriber/add.php
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
'Value' => 'Option 2'
)
),
'ConsentToTrack' => 'yes',
'Resubscribe' => true
));

Expand Down
4 changes: 3 additions & 1 deletion samples/subscriber/get.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@
'access_token' => 'your access token',
'refresh_token' => 'your refresh token');
$wrap = new CS_REST_Subscribers('Your list ID', $auth);
$result = $wrap->get('Email address');

//The 2nd argument will return the tracking preference of the subscriber - 'ConsentToTrack'
$result = $wrap->get('Email address', true);

echo "Result of GET /api/v3.1/subscribers/{list id}.{format}?email={email}\n<br />";
if($result->was_successful()) {
Expand Down
1 change: 1 addition & 0 deletions samples/subscriber/update.php
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
'Value' => 'Field Value'
)
),
'ConsentToTrack' => 'unchanged',
'Resubscribe' => true
));

Expand Down
2 changes: 2 additions & 0 deletions samples/transactional/classic_send.php
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@
);
$group_name = "PHP test group"; # optional, great for reporting, should not be unique message
$add_recipients_to_subscriber_list_ID = "6d0366fcee146ab9bdaf3247446bbfdd"; # optional, make sure you have permission
$consent_to_track = 'yes'; # Valid: 'yes', 'no', 'unchanged'

$options = array(
"TrackOpens" => true,
"TrackClicks" => true,
Expand Down
4 changes: 3 additions & 1 deletion samples/transactional/smart_send.php
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,9 @@
);

$add_recipients_to_subscriber_list = true;
$result = $wrap->send($complex_message, $add_recipients_to_subscriber_list);
$consent_to_track = 'yes'; # Valid: 'yes', 'no', 'unchanged'

$result = $wrap->send($complex_message, $consent_to_track, $add_recipients_to_subscriber_list);
echo "\nSent! Here's the response:\n";
var_dump($result->response);

25 changes: 25 additions & 0 deletions tests/csrest_lists_test.php
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,31 @@ function testget_active() {
$this->assertIdentical($expected_result, $result);
}

function testget_active_tracking() {
$raw_result = 'some subscribers';
$since = '2020';
$response_code = 200;
$deserialised = array('Subscriber 1', 'Subscriber 2');
$tracking_pref = 'true';

$call_options = $this->get_call_options($this->list_base_route.'active.json?date='.$since.'&includeTrackingPreference='.$tracking_pref);

$transport_result = array (
'code' => $response_code,
'response' => $raw_result
);

$expected_result = new CS_REST_Wrapper_Result($deserialised, $response_code);

$this->setup_transport_and_serialisation($transport_result, $call_options,
$deserialised, $raw_result, NULL, NULL, $response_code);

$result = $this->wrapper->get_active_subscribers($since, null, null, null, null, true);

$this->assertIdentical($expected_result, $result);
}


function testget_unconfirmed_subscribers() {
$raw_result = 'some subscribers';
$since = '2020';
Expand Down
6 changes: 4 additions & 2 deletions tests/csrest_segments_test.php
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,9 @@ function testget_segment_subscribers() {
$segment_id = 'abc123';
$response_code = 200;
$deserialised = array('Subscriber 1', 'Subscriber 2');
$call_options = $this->get_call_options($this->segment_base_route.'/active.json?date=');
$tracking_pref = 'false';

$call_options = $this->get_call_options($this->segment_base_route.'/active.json?date=&includeTrackingPreference='.$tracking_pref);

$transport_result = array (
'code' => $response_code,
Expand All @@ -132,7 +134,7 @@ function testget_segment_subscribers() {
$this->setup_transport_and_serialisation($transport_result, $call_options,
$deserialised, $raw_result, NULL, NULL, $response_code);

$result = $this->wrapper->get_subscribers();
$result = $this->wrapper->get_subscribers(null, null, null, null, null, false);

$this->assertIdentical($expected_result, $result);
}
Expand Down
Loading

0 comments on commit e343054

Please sign in to comment.