Merge pull request #72 from campaignmonitor/consent-to-track

Updates to API - using v3.2 with ConsentToTrack updates
campaignmonitor · May 25, 2018 · e343054 · e343054
2 parents e4e0c4b + 07850e1
commit e343054
Show file tree

Hide file tree

Showing 18 changed files with 114 additions and 38 deletions.
diff --git a/HISTORY.md b/HISTORY.md
@@ -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

diff --git a/class/base_classes.php b/class/base_classes.php
@@ -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');
@@ -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);
 
@@ -171,6 +171,7 @@ function __construct(
                 'host' => $host,
                 'protocol' => $protocol
             );
+
         }
 
         /**
@@ -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);
         }
 
@@ -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;
@@ -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);
         }
 
         /**

diff --git a/csrest_lists.php b/csrest_lists.php
@@ -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
          * {
@@ -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);
         }
 
         /**
@@ -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
          * {
@@ -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);
         }
 
         /**
@@ -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
          * {
@@ -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);
         }
 
         /**
@@ -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
          * {
@@ -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);
         }
 
         /**
@@ -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
          * {
@@ -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);
         }
 
         /**

diff --git a/csrest_segments.php b/csrest_segments.php
@@ -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
          * {
@@ -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);
         }
     }
 }
diff --git a/csrest_subscribers.php b/csrest_subscribers.php
@@ -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.
          *     )
@@ -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.
          *     )
@@ -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);
         }
 
         /**

diff --git a/csrest_transactional_classicemail.php b/csrest_transactional_classicemail.php
@@ -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);
         }
 

diff --git a/csrest_transactional_smartemail.php b/csrest_transactional_smartemail.php
@@ -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);
         }
 

diff --git a/samples/list/get_active_subscribers.php b/samples/list/get_active_subscribers.php
@@ -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);
 

diff --git a/samples/segment/get_subscribers.php b/samples/segment/get_subscribers.php
@@ -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);
 

diff --git a/samples/subscriber/add.php b/samples/subscriber/add.php
@@ -27,6 +27,7 @@
             'Value' => 'Option 2'
         )
     ),
+    'ConsentToTrack' => 'yes',
     'Resubscribe' => true
 ));
 

diff --git a/samples/subscriber/get.php b/samples/subscriber/get.php
@@ -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()) {

diff --git a/samples/subscriber/update.php b/samples/subscriber/update.php
@@ -15,6 +15,7 @@
             'Value' => 'Field Value'
         )
     ),
+    'ConsentToTrack' => 'unchanged',
     'Resubscribe' => true
 ));
 

diff --git a/samples/transactional/classic_send.php b/samples/transactional/classic_send.php
@@ -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,

diff --git a/samples/transactional/smart_send.php b/samples/transactional/smart_send.php
@@ -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);
 
diff --git a/tests/csrest_lists_test.php b/tests/csrest_lists_test.php
@@ -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';

diff --git a/tests/csrest_segments_test.php b/tests/csrest_segments_test.php
@@ -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, 
@@ -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);
     }