forked from campaignmonitor/createsend-php
-
Notifications
You must be signed in to change notification settings - Fork 0
/
csrest_subscribers.php
231 lines (216 loc) · 9.97 KB
/
csrest_subscribers.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
<?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
*
*/
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 $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_Subscribers (
$list_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_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
* )
* )
* '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)
* )
* )
* '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 $resubscribe Whether we should resubscribe any existing subscribers
* @param $queueSubscriptionBasedAutoResponders By default, subscription based auto responders do not trigger during an import. Pass a value of true to override this behaviour
* @param $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) {
return $this->get_request($this->_subscribers_base_route.'.json?email='.urlencode($email));
}
/**
* 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));
}
}