getresponse / providers / getresponse / GetResponseAPI.class.php

GetResponseAPI.class.php in GetResponse Forms by Optin Cat 1.4.1, at providers/getresponse/GetResponseAPI.class.php

605 lines 18.2 KB

Raw Download Zip

1	<?php
2
3	/**
4	* GetResponsePHP is a PHP5 implementation of the GetResponse API
5	* @internal This wrapper is incomplete and subject to change.
6	* @authors Ben Tadiar <ben@bentadiar.co.uk>, Robert Staddon <robert@abundantdesigns.com>
7	* @copyright Copyright (c) 2010 Assembly Studios
8	* @link http://www.assemblystudios.co.uk
9	* @package GetResponsePHP
10	* @version 0.1.1
11	*/
12
13	/**
14	* GetResponse Class
15	* @package GetResponsePHP
16	*/
17	class GetResponseApiOptinCat
18	{
19	/**
20	* GetResponse API key
21	* http://www.getresponse.com/my_api_key.html
22	* @var string
23	*/
24	public $apiKey = 'PASS_API_KEY_WHEN_INSTANTIATING_CLASS';
25
26	/**
27	* GetResponse API URL
28	* @var string
29	* @access private
30	*/
31	private $apiURL = 'http://api2.getresponse.com';
32
33	/**
34	* Text comparison operators used to filter results
35	* @var array
36	* @access private
37	*/
38	private $textOperators = array('EQUALS', 'NOT_EQUALS', 'CONTAINS', 'NOT_CONTAINS', 'MATCHES');
39
40	/**
41	* Check cURL extension is loaded and that an API key has been passed
42	* @param string $apiKey GetResponse API key
43	* @return void
44	*/
45	public function __construct($apiKey = null)
46	{
47	if(!extension_loaded('curl')) trigger_error('GetResponsePHP requires PHP cURL', E_USER_ERROR);
48	if(is_null($apiKey)) trigger_error('API key must be supplied', E_USER_ERROR);
49	$this->apiKey = $apiKey;
50	}
51
52	/**
53	* Test connection to the API, returns "pong" on success
54	* @return string
55	*/
56	public function ping()
57	{
58	$request = $this->prepRequest('ping');
59	$response = $this->execute($request);
60	return $response->ping;
61	}
62
63	/**
64	* Get basic user account information
65	* @return object
66	*/
67	public function getAccountInfo()
68	{
69	$request = $this->prepRequest('get_account_info');
70	$response = $this->execute($request);
71	return $response;
72	}
73
74	/**
75	* Get list of email addresses assigned to account
76	* @return object
77	*/
78	public function getAccountFromFields()
79	{
80	$request = $this->prepRequest('get_account_from_fields');
81	$response = $this->execute($request);
82	return $response;
83	}
84
85	/**
86	* Get single email address assigned to an account using the account From Field ID
87	* @param string $id
88	* @return object
89	*/
90	public function getAccountFromFieldByID($id)
91	{
92	$request = $this->prepRequest('get_account_from_field', array('account_from_field' => $id));
93	$response = $this->execute($request);
94	return $response;
95	}
96
97	/**
98	* Get single email address assigned to an account using an email address
99	* @param string $email
100	* @return object
101	*/
102	public function getAccountFromFieldsByEmail($email)
103	{
104	$request = $this->prepRequest('get_account_from_fields');
105	$response = $this->execute($request);
106	foreach($response as $key => $account) if($account->email!=$email) unset($response->$key);
107	return $response;
108	}
109
110	/**
111	* Get a list of active campaigns, optionally filtered
112	* @param string $operator Comparison operator
113	* @param string $comparison Text/expression to compare against
114	* @return object
115	*/
116	public function getCampaigns($operator = 'CONTAINS', $comparison = '%')
117	{
118	$params = null;
119	if(in_array($operator, $this->textOperators)) $params = array('name' => array($operator => $comparison));
120	$request = $this->prepRequest('get_campaigns', $params);
121	$response = $this->execute($request);
122	return $response;
123	}
124
125	/**
126	* Return a campaign by ID
127	* @param string $id Campaign ID
128	* @return object
129	*/
130	public function getCampaignByID($id)
131	{
132	$request = $this->prepRequest('get_campaign', array('campaign' => $id));
133	$response = $this->execute($request);
134	return $response;
135	}
136
137	/**
138	* Return a campaign ID by name
139	* @param string $name Campaign Name
140	* @return string Campaign ID
141	*/
142	public function getCampaignByName($name)
143	{
144	$request = $this->prepRequest('get_campaigns', array('name' => array('EQUALS' => $name)));
145	$response = $this->execute($request);
146	return key($response);
147	}
148
149	/**
150	* Return a list of messages, optionally filtered by multiple conditions
151	* @todo Implement all conditions, this is unfinished
152	* @param array\|null $campaigns Optional argument to narrow results by campaign ID
153	* @param string\|null $type Optional argument to narrow results by "newsletter", "autoresponder", or "draft"
154	* @param string $operator
155	* @param string $comparison
156	* @return object
157	*/
158	public function getMessages($campaigns = null, $type = null, $operator = 'CONTAINS', $comparison = '%')
159	{
160	$params = null;
161	if(is_array($campaigns)) $params['campaigns'] = $campaigns;
162	if(is_string($type)) $params['type'] = $type;
163	$request = $this->prepRequest('get_messages', $params);
164	$response = $this->execute($request);
165	return $response;
166	}
167
168	/**
169	* Return a message by ID
170	* @param string $id Message ID
171	* @return object
172	*/
173	public function getMessageByID($id)
174	{
175	$request = $this->prepRequest('get_message', array('message' => $id));
176	$response = $this->execute($request);
177	return $response;
178	}
179
180	/**
181	* Return an autoresponder message from a campaign by Cycle Day
182	* @param string $campaign Campaign ID
183	* @param string $cycle_day Cycle Day
184	* @return object
185	*/
186	public function getMessageByCycleDay($campaign, $cycle_day)
187	{
188	$params['campaigns'] = array($campaign);
189	$params['type'] = "autoresponder";
190	$request = $this->prepRequest('get_messages', $params);
191	$response = $this->execute($request);
192	foreach($response as $key => $message) if($message->day_of_cycle!=$cycle_day) unset($response->$key);
193	return $response;
194	}
195
196	/**
197	* Return message contents by ID
198	* @param string $id Message ID
199	* @return object
200	*/
201	public function getMessageContents($id)
202	{
203	$request = $this->prepRequest('get_message_contents', array('message' => $id));
204	$response = $this->execute($request);
205	return $response;
206	}
207
208	/**
209	* Return message statistics
210	* @param string $message Message ID
211	* @param string $grouping grouping
212	* @return object\|null
213	*/
214	public function getMessageStats($message, $grouping = "yearly")
215	{
216	$params['message'] = $message;
217	$params['grouping'] = $grouping;
218	$request = $this->prepRequest('get_message_stats', $params);
219	$response = $this->execute($request);
220	return $response;
221	}
222
223	/**
224	* Return autoresponder message contents by Cycle Day
225	* @param string $campaign Campaign ID
226	* @param string $cycle_day Cycle Day
227	* @return object\|null
228	*/
229	public function getMessageContentsByCycleDay($campaign, $cycle_day)
230	{
231	$params['campaigns'] = array($campaign);
232	$params['type'] = "autoresponder";
233	$request = $this->prepRequest('get_messages', $params);
234	$response = $this->execute($request);
235	foreach($response as $key => $message) if($message->day_of_cycle==$cycle_day) return $this->getMessageContents($key);
236	return null;
237	}
238
239	/**
240	* Add autoresponder to a campaign at a specific day of cycle
241	* @param string $campaign Campaign ID
242	* @param string $subject Subject of message
243	* @param array $contents Allowed keys are "plain" and "html", at least one is mandatory
244	* @param int $cycle_day
245	* @param string $from_field From Field ID obtained through getAccountFromFields()
246	* @param array $flags Enables extra functionality for a message: "clicktrack", "subscription_reminder", "openrate", "google_analytics"
247	* @return object
248	*/
249	public function addAutoresponder($campaign, $subject, $cycle_day, $html = null, $plain = null, $from_field = null, $flags = null)
250	{
251	$params = array('campaign' => $campaign, 'subject' => $subject, 'day_of_cycle' => $cycle_day);
252	if(is_string($html)) $params['contents']['html'] = $html;
253	if(is_string($plain)) $params['contents']['plain'] = $plain;
254	if(is_string($from_field)) $params['from_field'] = $from_field;
255	if(is_array($flags)) $params['flags'] = $flags;
256	$request = $this->prepRequest('add_autoresponder', $params);
257	$response = $this->execute($request);
258	return $response;
259	}
260
261	/**
262	* Delete an autoresponder
263	* @param string $id
264	* @return object
265	*/
266	public function deleteAutoresponder($id)
267	{
268	$request = $this->prepRequest('delete_autoresponder', array('message' => $id));
269	$response = $this->execute($request);
270	return $response;
271	}
272
273	/**
274	* Return a list of contacts, optionally filtered by multiple conditions
275	* @todo Implement all conditions, this is unfinished
276	* @param array\|null $campaigns Optional argument to narrow results by campaign ID
277	* @param string $operator Optional argument to change operator (default is 'CONTAINS')
278	* See https://github.com/GetResponse/DevZone/tree/master/API#operators for additional operator options
279	* @param string $comparison
280	* @param array $fields (an associative array, the keys of which should enable/disable comparing name or email)
281	* @return object
282	*/
283	public function getContacts($campaigns = null, $operator = 'CONTAINS', $comparison = '%', $fields = array('name' => true, 'email' => false))
284	{
285	$params = null;
286	if(is_array($campaigns)) $params['campaigns'] = $campaigns;
287	if($fields['name']) $params['name'] = $this->prepTextOp($operator, $comparison);
288	if($fields['email']) $params['email'] = $this->prepTextOp($operator, $comparison);
289	$request = $this->prepRequest('get_contacts', $params);
290	$response = $this->execute($request);
291	return $response;
292	}
293
294	/**
295	* Return a list of contacts by email address (optionally narrowed by campaign)
296	* @param string $email Email Address of Contact (or a string contained in the email address)
297	* @param array\|null $campaigns Optional argument to narrow results by campaign ID
298	* @param string $operator Optional argument to change operator (default is 'CONTAINS')
299	* See https://github.com/GetResponse/DevZone/tree/master/API#operators for additional operator options
300	* @return object
301	*/
302	public function getContactsByEmail($email, $campaigns = null, $operator = 'CONTAINS')
303	{
304	$params = null;
305	$params['email'] = $this->prepTextOp($operator, $email);
306	if(is_array($campaigns)) $params['campaigns'] = $campaigns;
307	$request = $this->prepRequest('get_contacts', $params);
308	$response = $this->execute($request);
309	return $response;
310	}
311
312	/**
313	* Return a list of contacts filtered by custom contact information
314	* $customs is an associative arrays, the keys of which should correspond to the
315	* custom field names of the customers you wish to retrieve.
316	* @param array\|null $campaigns Optional argument to narrow results by campaign ID
317	* @param string $operator
318	* @param array $customs
319	* @param string $comparison
320	* @return object
321	*/
322	public function getContactsByCustoms($campaigns = null, $customs, $operator = 'EQUALS')
323	{
324	$params = null;
325	if(is_array($campaigns)) $params['campaigns'] = $campaigns;
326	if(!is_array($customs)) trigger_error('Second argument must be an array', E_USER_ERROR);
327	foreach($customs as $key => $val) $params['customs'][] = array('name' => $key, 'content' => $this->prepTextOp($operator, $val));
328	$request = $this->prepRequest('get_contacts', $params);
329	$response = $this->execute($request);
330	return $response;
331	}
332
333	/**
334	* Return a contact by ID
335	* @param string $id User ID
336	* @return object
337	*/
338	public function getContactByID($id)
339	{
340	$request = $this->prepRequest('get_contact', array('contact' => $id));
341	$response = $this->execute($request);
342	return $response;
343	}
344
345
346	/**
347	* Set a contact name
348	* @param string $id User ID
349	* @return object
350	*/
351	public function setContactName($id, $name)
352	{
353	$request = $this->prepRequest('set_contact_name', array('contact' => $id, 'name' => $name));
354	$response = $this->execute($request);
355	return $response;
356	}
357
358	/**
359	* Set a contact cycle
360	* @param string $id User ID
361	* @param int $cycle_day Cycle Day
362	* @return object
363	*/
364	public function setContactCycle($id, $cycle_day)
365	{
366	$request = $this->prepRequest('set_contact_cycle', array('contact' => $id, 'cycle_day' => $cycle_day));
367	$response = $this->execute($request);
368	return $response;
369	}
370
371	/**
372	* Set a contact campaign
373	* @param string $id User ID
374	* @param string $campaign Campaign ID
375	* @return object
376	*/
377	public function setContactCampaign($id, $campaign)
378	{
379	$request = $this->prepRequest('move_contact', array('contact' => $id, 'campaign' => $campaign));
380	$response = $this->execute($request);
381	return $response;
382	}
383
384	/**
385	* Return a contacts custom information
386	* @param string $id User ID
387	* @return object
388	*/
389	public function getContactCustoms($id)
390	{
391	$request = $this->prepRequest('get_contact_customs', array('contact' => $id));
392	$response = $this->execute($request);
393	return $response;
394	}
395
396
397	/**
398	* Set custom contact information
399	* $customs is an associative array, the keys of which should correspond to the
400	* custom field name you wish to add/modify/remove.
401	* Actions: added if not present, updated if present, removed if value is null
402	* @todo Implement multivalue customs.
403	* @param string $id User ID
404	* @param array $customs
405	* @return object
406	*/
407	public function setContactCustoms($id, $customs)
408	{
409	if(!is_array($customs)) trigger_error('Second argument must be an array', E_USER_ERROR);
410	foreach($customs as $key => $val) $params[] = array('name' => $key, 'content' => $val);
411	$request = $this->prepRequest('set_contact_customs', array('contact' => $id, 'customs' => $params));
412	$response = $this->execute($request);
413	return $response;
414	}
415
416	/**
417	* Return a contacts GeoIP
418	* @param string $id User ID
419	* @return object
420	*/
421	public function getContactGeoIP($id)
422	{
423	$request = $this->prepRequest('get_contact_geoip', array('contact' => $id));
424	$response = $this->execute($request);
425	return $response;
426	}
427
428	/**
429	* List dates when the messages were opened by contacts
430	* @param string $id User ID
431	* @return object
432	*/
433	public function getContactOpens($id)
434	{
435	$request = $this->prepRequest('get_contact_opens', array('contact' => $id));
436	$response = $this->execute($request);
437	return $response;
438	}
439
440	/**
441	* List dates when the links in messages were clicked by contacts
442	* @param string $id User ID
443	* @return object
444	*/
445	public function getContactClicks($id)
446	{
447	$request = $this->prepRequest('get_contact_clicks', array('contact' => $id));
448	$response = $this->execute($request);
449	return $response;
450	}
451
452	/**
453	* Validate an IPv4 IP address
454	*
455	* @param string $ip
456	* @return boolean - true/false
457	*/
458	function isValidIP($ip)
459	{
460	return preg_match('/^(([1-9]?[0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5]).){3}([1-9]?[0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])$/',$ip);
461	}
462
463
464	/**
465	* Add contact to the specified list (Requires email verification by contact)
466	* The return value of this function will be "queued", and on subsequent
467	* submission of the same email address will be "duplicated".
468	* @param string $campaign Campaign ID
469	* @param string $name Name of contact
470	* @param string $email Email address of contact
471	* @param string $action Standard, insert or update
472	* @param int $cycle_day
473	* @param array $customs
474	* @return object
475	*/
476	public function addContact($campaign, $name, $email, $action = 'standard', $cycle_day = 0, $customs = array())
477	{
478
479	$ip = $_SERVER['REMOTE_ADDR'];
480
481	if (!$this->isValidIP($ip)) $ip = '127.0.0.1';
482
483	$params = array('campaign' => $campaign, 'action' => $action,
484	'email' => $email, 'cycle_day' => $cycle_day, 'ip' => $ip);
485
486	if(!empty($name)) {
487	$params['name'] = $name;
488	}
489
490	if(!empty($customs)) {
491	foreach($customs as $key => $val) $c[] = array('name' => $key, 'content' => $val);
492	$params['customs'] = $c;
493	}
494	$request = $this->prepRequest('add_contact', $params);
495	$response = $this->execute($request);
496	return $response;
497	}
498
499	/**
500	* Delete a contact
501	* @param string $id
502	* @return object
503	*/
504	public function deleteContact($id)
505	{
506	$request = $this->prepRequest('delete_contact', array('contact' => $id));
507	$response = $this->execute($request);
508	return $response;
509	}
510
511	/**
512	* Get blacklist masks on account level
513	* Account is determined by API key
514	* @return object
515	*/
516	public function getAccountBlacklist()
517	{
518	$request = $this->prepRequest('get_account_blacklist');
519	$response = $this->execute($request);
520	return $response;
521	}
522
523	/**
524	* Adds blacklist mask on account level
525	* @param string $mask
526	* @return object
527	*/
528	public function addAccountBlacklist($mask)
529	{
530	$request = $this->prepRequest('add_account_blacklist', array('mask' => $mask));
531	$response = $this->execute($request);
532	return $response;
533	}
534
535	/**
536	* Delete blacklist mask on account level
537	* @param string $mask
538	* @return object
539	*/
540	public function deleteAccountBlacklist($mask)
541	{
542	$request = $this->prepRequest('delete_account_blacklist', array('mask' => $mask));
543	$response = $this->execute($request);
544	return $response;
545	}
546
547	/**
548	* Return a key => value array for text comparison
549	* @param string $operator
550	* @param mixed $comparison
551	* @return array
552	* @access private
553	*/
554	private function prepTextOp($operator, $comparison)
555	{
556	if(!in_array($operator, $this->textOperators)) trigger_error('Invalid text operator', E_USER_ERROR);
557	if($operator === 'CONTAINS') $comparison = '%'.$comparison.'%';
558	return array($operator => $comparison);
559	}
560
561	/**
562	* Return array as a JSON encoded string
563	* @param string $method API method to call
564	* @param array $params Array of parameters
565	* @return string JSON encoded string
566	* @access private
567	*/
568	private function prepRequest($method, $params = null, $id = null)
569	{
570	$array = array($this->apiKey);
571	if(!is_null($params)) $array[1] = $params;
572	$request = json_encode(array('method' => $method, 'params' => $array, 'id' => $id));
573	return $request;
574	}
575
576	/**
577	* Executes an API call
578	* @param string $request JSON encoded array
579	* @return object
580	* @access private
581	*/
582	private function execute($request)
583	{
584	$handle = curl_init($this->apiURL);
585	curl_setopt($handle, CURLOPT_POST, 1);
586	curl_setopt($handle, CURLOPT_POSTFIELDS, $request);
587	curl_setopt($handle, CURLOPT_HEADER, 'Content-type: application/json');
588	curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
589	$response = json_decode(curl_exec($handle));
590	if(curl_error($handle)) trigger_error(curl_error($handle), E_USER_ERROR);
591	$httpCode = curl_getinfo($handle, CURLINFO_HTTP_CODE);
592	if(!(($httpCode == '200') \|\| ($httpCode == '204'))) trigger_error('API call failed. Server returned status code '.$httpCode, E_USER_ERROR);
593	curl_close($handle);
594
595	if ($response->error && defined ( 'FCA_EOI_DEBUG' ) ) {
596	echo 'Whoops, something is broken: <br>';
597	echo '<h2>'.$response->error->message.'</h2>';
598	wp_die();
599	}
600	if(!$response->error) return $response->result;
601	}
602	}
603
604	?>
605