s2member / includes / _xtnls / mailchimp / nc-mcapi.inc.php

nc-mcapi.inc.php in s2Member – Excellent for All Kinds of Memberships, Content Restriction Paywalls & Member Access Subscriptions 110913, at includes/_xtnls/mailchimp/nc-mcapi.inc.php

2,516 lines 140.6 KB

Raw Download Zip

1	<?php
2	/**
3	* MailChimp® API Class.
4	*
5	* Copyright {@link http://www.mailchimp.com/ MailChimp®}.
6	*
7	* Modified by {@link http://www.websharks-inc.com/ WebSharks, Inc.}.
8	* Uses a custom class name to avoid conflicts with other instances.
9	*
10	* This version has also been modified to use:
11	* {@link s2Member\Utilities\c_ws_plugin__s2member_utils_urls::remote()}
12	*
13	* @package Xtnls\MailChimp
14	* @since 3.0
15	*/
16	class NC_MCAPI {
17	var $version = "1.3";
18	var $errorMessage;
19	var $errorCode;
20
21	/**
22	* Cache the information on the API location on the server
23	*/
24	var $apiUrl;
25
26	/**
27	* Default to a 300 second timeout on server calls
28	*/
29	var $timeout = 300;
30
31	/**
32	* Default to a 8K chunk size
33	*/
34	var $chunkSize = 8192;
35
36	/**
37	* Cache the user api_key so we only have to log in once per client instantiation
38	*/
39	var $api_key;
40
41	/**
42	* Cache the user api_key so we only have to log in once per client instantiation
43	*/
44	var $secure = false;
45
46	/**
47	* Connect to the MailChimp API for a given list.
48	*
49	* @param string $apikey Your MailChimp apikey
50	* @param string $secure Whether or not this should use a secure connection
51	*/
52	function NC_MCAPI($apikey, $secure=false) {
53	$this->secure = $secure;
54	$this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
55	$this->api_key = $apikey;
56	}
57	function setTimeout($seconds){
58	if (is_int($seconds)){
59	$this->timeout = $seconds;
60	return true;
61	}
62	}
63	function getTimeout(){
64	return $this->timeout;
65	}
66	function useSecure($val){
67	if ($val===true){
68	$this->secure = true;
69	} else {
70	$this->secure = false;
71	}
72	}
73
74	/**
75	* Unschedule a campaign that is scheduled to be sent in the future
76	*
77	* @section Campaign Related
78	* @example mcapi_campaignUnschedule.php
79	* @example xml-rpc_campaignUnschedule.php
80	*
81	* @param string $cid the id of the campaign to unschedule
82	* @return boolean true on success
83	*/
84	function campaignUnschedule($cid) {
85	$params = array();
86	$params["cid"] = $cid;
87	return $this->callServer("campaignUnschedule", $params);
88	}
89
90	/**
91	* Schedule a campaign to be sent in the future
92	*
93	* @section Campaign Related
94	* @example mcapi_campaignSchedule.php
95	* @example xml-rpc_campaignSchedule.php
96	*
97	* @param string $cid the id of the campaign to schedule
98	* @param string $schedule_time the time to schedule the campaign. For A/B Split "schedule" campaigns, the time for Group A - in YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
99	* @param string $schedule_time_b optional -the time to schedule Group B of an A/B Split "schedule" campaign - in YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
100	* @return boolean true on success
101	*/
102	function campaignSchedule($cid, $schedule_time, $schedule_time_b=NULL) {
103	$params = array();
104	$params["cid"] = $cid;
105	$params["schedule_time"] = $schedule_time;
106	$params["schedule_time_b"] = $schedule_time_b;
107	return $this->callServer("campaignSchedule", $params);
108	}
109
110	/**
111	* Resume sending an AutoResponder or RSS campaign
112	*
113	* @section Campaign Related
114	*
115	* @param string $cid the id of the campaign to pause
116	* @return boolean true on success
117	*/
118	function campaignResume($cid) {
119	$params = array();
120	$params["cid"] = $cid;
121	return $this->callServer("campaignResume", $params);
122	}
123
124	/**
125	* Pause an AutoResponder orRSS campaign from sending
126	*
127	* @section Campaign Related
128	*
129	* @param string $cid the id of the campaign to pause
130	* @return boolean true on success
131	*/
132	function campaignPause($cid) {
133	$params = array();
134	$params["cid"] = $cid;
135	return $this->callServer("campaignPause", $params);
136	}
137
138	/**
139	* Send a given campaign immediately. For RSS campaigns, this will "start" them.
140	*
141	* @section Campaign Related
142	*
143	* @example mcapi_campaignSendNow.php
144	* @example xml-rpc_campaignSendNow.php
145	*
146	* @param string $cid the id of the campaign to send
147	* @return boolean true on success
148	*/
149	function campaignSendNow($cid) {
150	$params = array();
151	$params["cid"] = $cid;
152	return $this->callServer("campaignSendNow", $params);
153	}
154
155	/**
156	* Send a test of this campaign to the provided email address
157	*
158	* @section Campaign Related
159	*
160	* @example mcapi_campaignSendTest.php
161	* @example xml-rpc_campaignSendTest.php
162	*
163	* @param string $cid the id of the campaign to test
164	* @param array $test_emails an array of email address to receive the test message
165	* @param string $send_type optional by default (null) both formats are sent - "html" or "text" send just that format
166	* @return boolean true on success
167	*/
168	function campaignSendTest($cid, $test_emails=array (
169	), $send_type=NULL) {
170	$params = array();
171	$params["cid"] = $cid;
172	$params["test_emails"] = $test_emails;
173	$params["send_type"] = $send_type;
174	return $this->callServer("campaignSendTest", $params);
175	}
176
177	/**
178	* Allows one to test their segmentation rules before creating a campaign using them
179	*
180	* @section Campaign Related
181	* @example mcapi_campaignSegmentTest.php
182	* @example xml-rpc_campaignSegmentTest.php
183	*
184	* @param string $list_id the list to test segmentation on - get lists using lists()
185	* @param array $options with 2 keys:
186	string "match" controls whether to use AND or OR when applying your options - expects "<strong>any</strong>" (for OR) or "<strong>all</strong>" (for AND)
187	array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row must contain 3 keys - "<strong>field</strong>", "<strong>op</strong>", and "<strong>value</strong>" - and possibly a fourth, "<strong>extra</strong>", based on these definitions:
188
189	Field = "<strong>date</strong>" : Select based on signup date
190	Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
191	Valid Values:
192	string last_campaign_sent uses the date of the last campaign sent
193	string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns()
194	string YYYY-MM-DD - any date in the form of YYYY-MM-DD - <em>note:</em> anything that appears to start with YYYY will be treated as a date
195
196	Field = "<strong>interests-X</strong>": where X is the Grouping Id from listInterestGroupings()
197	Valid Op(erations): <strong>one</strong> / <strong>none</strong> / <strong>all</strong>
198	Valid Values: a comma delimited of interest groups for the list - see listInterestGroupings()
199
200	Field = "<strong>aim</strong>"
201	Valid Op(erations): <strong>open</strong> / <strong>noopen</strong> / <strong>click</strong> / <strong>noclick</strong>
202	Valid Values: "<strong>any</strong>" or a valid AIM-enabled Campaign that has been sent
203
204	Field = "<strong>rating</strong>" : allows matching based on list member ratings
205	Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (>) / <strong>lt</strong> (<)
206	Valid Values: a number between 0 and 5
207
208	Field = "<strong>ecomm_prod</strong>" or "<strong>ecomm_prod</strong>": allows matching product and category names from purchases
209	Valid Op(erations):
210	<strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (>) / <strong>lt</strong> (<) / <strong>like</strong> (like '%blah%') / <strong>nlike</strong> (not like '%blah%') / <strong>starts</strong> (like 'blah%') / <strong>ends</strong> (like '%blah')
211	Valid Values: any string
212
213	Field = "<strong>ecomm_spent_one</strong>" or "<strong>ecomm_spent_all</strong>" : allows matching purchase amounts on a single order or all orders
214	Valid Op(erations): <strong>gt</strong> (>) / <strong>lt</strong> (<)
215	Valid Values: a number
216
217	Field = "<strong>ecomm_date</strong>" : allow matching based on order dates
218	Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
219	Valid Values:
220	string YYYY-MM-DD - any date in the form of YYYY-MM-DD
221
222	Field = "<strong>social_gender</strong>" : allows matching against the gender acquired from SocialPro
223	Valid Op(eration): <strong>eq</strong> (is) / <strong>ne</strong> (is not)
224	Valid Values: male, female
225
226	Field = "<strong>social_age</strong>" : allows matching against the age acquired from SocialPro
227	Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (>) / <strong>lt</strong> (<)
228	Valid Values: any number
229
230	Field = "<strong>social_influence</strong>" : allows matching against the influence acquired from SocialPro
231	Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (>) / <strong>lt</strong> (<)
232	Valid Values: a number between 0 and 5
233
234	Field = "<strong>social_network</strong>" :
235	Valid Op(erations): <strong>member</strong> (is a member of) / <strong>notmember</strong> (is not a member of)
236	Valid Values: twitter, facebook, myspace, linkedin, flickr
237
238	Field = "<strong>static_segment</strong>" :
239	Valid Op(eration): <strong>eq</strong> (is in) / <strong>ne</strong> (is not in)
240	Valid Values: an int - get from listStaticSegments()
241
242	Field = An <strong>Address</strong> Merge Var. Use <strong>Merge0-Merge30</strong> or the <strong>Custom Tag</strong> you've setup for your merge field - see listMergeVars(). Note, Address fields can still be used with the default operations below - this section is broken out solely to highlight the differences in using the geolocation routines.
243	Valid Op(erations): <strong>geoin</strong>
244	Valid Values: The number of miles an address should be within
245	Extra Value: The Zip Code to be used as the center point
246
247	Default Field = A Merge Var. Use <strong>Merge0-Merge30</strong> or the <strong>Custom Tag</strong> you've setup for your merge field - see listMergeVars()
248	Valid Op(erations):
249	<strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (>) / <strong>lt</strong> (<) / <strong>like</strong> (like '%blah%') / <strong>nlike</strong> (not like '%blah%') / <strong>starts</strong> (like 'blah%') / <strong>ends</strong> (like '%blah')
250	Valid Values: any string
251	* @return int total The total number of subscribers matching your segmentation options
252	*/
253	function campaignSegmentTest($list_id, $options) {
254	$params = array();
255	$params["list_id"] = $list_id;
256	$params["options"] = $options;
257	return $this->callServer("campaignSegmentTest", $params);
258	}
259
260	/**
261	* Create a new draft campaign to send. You <strong>can not</strong> have more than 32,000 campaigns in your account.
262	*
263	* @section Campaign Related
264	* @example mcapi_campaignCreate.php
265	* @example xml-rpc_campaignCreate.php
266	* @example xml-rpc_campaignCreateABSplit.php
267	* @example xml-rpc_campaignCreateRss.php
268	*
269	* @param string $type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "trans", "auto"
270	* @param array $options a hash of the standard options for this campaign :
271	string list_id the list to send this campaign to- get lists using lists()
272	string subject the subject line for your campaign message
273	string from_email the From: email address for your campaign message
274	string from_name the From: name for your campaign message (not an email address)
275	string to_name the To: name recipients will see (not email address)
276	int template_id optional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
277	int gallery_template_id optional - use a template from the public gallery to generate the HTML content of the campaign (takes precendence over base template options)
278	int base_template_id optional - use this a base/start-from-scratch template to generate the HTML content of the campaign
279	int folder_id optional - automatically file the new campaign in the folder_id passed. Get using folders() - note that Campaigns and Autoresponders have separate folder setupsn
280	array tracking optional - set which recipient actions will be tracked, as a struct of boolean values with the following keys: "opens", "html_clicks", and "text_clicks". By default, opens and HTML clicks will be tracked. Click tracking can not be disabled for Free accounts.
281	string title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
282	boolean authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
283	array analytics optional - if provided, use a struct with "service type" as a key and the "service tag" as a value. For Google, this should be "google"=>"your_google_analytics_key_here". Note that only "google" is currently supported - a Google Analytics tags will be added to all links in the campaign with this string attached. Others may be added in the future
284	boolean auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
285	boolean inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
286	boolean generate_text optional Whether of not to auto-generate your Text content from the HTML content. Note that this will be ignored if the Text part of the content passed is not empty, defaults to false.
287	boolean auto_tweet optional If set, this campaign will be auto-tweeted when it is sent - defaults to false. Note that if a Twitter account isn't linked, this will be silently ignored.
288	boolean timewarp optional If set, this campaign must be scheduled 24 hours in advance of sending - default to false. Only valid for "regular" campaigns and "absplit" campaigns that split on schedule_time.
289	boolean ecomm360 optional If set, our <a href="http://www.mailchimp.com/blog/ecommerce-tracking-plugin/" target="_blank">Ecommerce360 tracking</a> will be enabled for links in the campaign
290
291	* @param array $content the content for this campaign - use a struct with the following keys:
292	string html for pasted HTML content
293	string text for the plain-text version
294	string url to have us pull in content from a URL. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
295	string archive to send a Base64 encoded archive file for us to import all media from. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
296	string archive_type optional - only necessary for the "archive" option. Supported formats are: zip, tar.gz, tar.bz2, tar, tgz, tbz . If not included, we will default to zip
297
298	If you chose a template instead of pasting in your HTML content, then use "html_" followed by the template sections as keys - for example, use a key of "html_MAIN" to fill in the "MAIN" section of a template. Supported template sections include: "html_HEADER", "html_MAIN", "html_SIDECOLUMN", and "html_FOOTER"
299	* @param array $segment_opts optional - if you wish to do Segmentation with this campaign this array should contain: see campaignSegmentTest(). It's suggested that you test your options against campaignSegmentTest(). Also, "trans" campaigns <strong>do not</strong> support segmentation.
300	* @param array $type_opts optional -
301	For RSS Campaigns this, array should contain:
302	string url the URL to pull RSS content from - it will be verified and must exist
303	string schedule optional one of "daily", "weekly", "monthly" - defaults to "daily"
304	string schedule_hour optional an hour between 0 and 24 - default to 4 (4am <em>local time</em>) - applies to all schedule types
305	string schedule_weekday optional for "weekly" only, a number specifying the day of the week to send: 0 (Sunday) - 6 (Saturday) - defaults to 1 (Monday)
306	string schedule_monthday optional for "monthly" only, a number specifying the day of the month to send (1 - 28) or "last" for the last day of a given month. Defaults to the 1st day of the month
307
308	For A/B Split campaigns, this array should contain:
309	string split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
310	string pick_winner How the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
311	int wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
312	int wait_time optional the number of units to wait before auto-selecting a winner - defaults to 1, so if not set, a winner will be selected after 1 Day.
313	int split_size optional this is a percentage of what size the Campaign's List plus any segmentation options results in. "schedule" type forces 50%, all others default to 10%
314	string from_name_a optional sort of, required when split_test is "from_name"
315	string from_name_b optional sort of, required when split_test is "from_name"
316	string from_email_a optional sort of, required when split_test is "from_name"
317	string from_email_b optional sort of, required when split_test is "from_name"
318	string subject_a optional sort of, required when split_test is "subject"
319	string subject_b optional sort of, required when split_test is "subject"
320
321	For AutoResponder campaigns, this array should contain:
322	string offset-units one of "day", "week", "month", "year" - required
323	string offset-time optional, sort of - the number of units must be a number greater than 0 for signup based autoresponders
324	string offset-dir either "before" or "after"
325	string event optional "signup" (default) to base this on double-optin signup, "date" or "annual" to base this on merge field in the list
326	string event-datemerge optional sort of, this is required if the event is "date" or "annual"
327
328	*
329	* @return string the ID for the created campaign
330	*/
331	function campaignCreate($type, $options, $content, $segment_opts=NULL, $type_opts=NULL) {
332	$params = array();
333	$params["type"] = $type;
334	$params["options"] = $options;
335	$params["content"] = $content;
336	$params["segment_opts"] = $segment_opts;
337	$params["type_opts"] = $type_opts;
338	return $this->callServer("campaignCreate", $params);
339	}
340
341	/** Update just about any setting for a campaign that has <em>not</em> been sent. See campaignCreate() for details.
342	*
343	*
344	* Caveats:<br/><ul>
345	* <li>If you set list_id, all segmentation options will be deleted and must be re-added.</li>
346	* <li>If you set template_id, you need to follow that up by setting it's 'content'</li>
347	* <li>If you set segment_opts, you should have tested your options against campaignSegmentTest() as campaignUpdate() will not allow you to set a segment that includes no members.</li></ul>
348	* @section Campaign Related
349	*
350	* @example mcapi_campaignUpdate.php
351	* @example mcapi_campaignUpdateAB.php
352	* @example xml-rpc_campaignUpdate.php
353	* @example xml-rpc_campaignUpdateAB.php
354	*
355	* @param string $cid the Campaign Id to update
356	* @param string $name the parameter name ( see campaignCreate() ). For items in the <strong>options</strong> array, this will be that parameter's name (subject, from_email, etc.). Additional parameters will be that option name (content, segment_opts). "type_opts" will be the name of the type - rss, auto, trans, etc.
357	* @param mixed $value an appropriate value for the parameter ( see campaignCreate() ). For items in the <strong>options</strong> array, this will be that parameter's value. For additional parameters, this is the same value passed to them.
358	* @return boolean true if the update succeeds, otherwise an error will be thrown
359	*/
360	function campaignUpdate($cid, $name, $value) {
361	$params = array();
362	$params["cid"] = $cid;
363	$params["name"] = $name;
364	$params["value"] = $value;
365	return $this->callServer("campaignUpdate", $params);
366	}
367
368	/** Replicate a campaign.
369	*
370	* @section Campaign Related
371	*
372	* @example mcapi_campaignReplicate.php
373	*
374	* @param string $cid the Campaign Id to replicate
375	* @return string the id of the replicated Campaign created, otherwise an error will be thrown
376	*/
377	function campaignReplicate($cid) {
378	$params = array();
379	$params["cid"] = $cid;
380	return $this->callServer("campaignReplicate", $params);
381	}
382
383	/** Delete a campaign. Seriously, "poof, gone!" - be careful!
384	*
385	* @section Campaign Related
386	*
387	* @example mcapi_campaignDelete.php
388	*
389	* @param string $cid the Campaign Id to delete
390	* @return boolean true if the delete succeeds, otherwise an error will be thrown
391	*/
392	function campaignDelete($cid) {
393	$params = array();
394	$params["cid"] = $cid;
395	return $this->callServer("campaignDelete", $params);
396	}
397
398	/**
399	* Get the list of campaigns and their details matching the specified filters
400	*
401	* @section Campaign Related
402	* @example mcapi_campaigns.php
403	* @example xml-rpc_campaigns.php
404	*
405	* @param array $filters a hash of filters to apply to this query - all are optional:
406	string campaign_id optional - return a single campaign using a know campaign_id
407	string list_id optional - the list to send this campaign to- get lists using lists(). Accepts multiples separated by commas when not using exact matching.
408	int folder_id optional - only show campaigns from this folder id - get folders using campaignFolders(). Accepts multiples separated by commas when not using exact matching.
409	int template_id optional - only show campaigns using this template id - get templates using templates(). Accepts multiples separated by commas when not using exact matching.
410	string status optional - return campaigns of a specific status - one of "sent", "save", "paused", "schedule", "sending". Accepts multiples separated by commas when not using exact matching.
411	string type optional - return campaigns of a specific type - one of "regular", "plaintext", "absplit", "rss", "trans", "auto". Accepts multiples separated by commas when not using exact matching.
412	string from_name optional - only show campaigns that have this "From Name"
413	string from_email optional - only show campaigns that have this "Reply-to Email"
414	string title optional - only show campaigns that have this title
415	string subject optional - only show campaigns that have this subject
416	string sendtime_start optional - only show campaigns that have been sent since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
417	string sendtime_end optional - only show campaigns that have been sent before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
418	boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true. Using this disables the use of any filters that accept multiples.
419	* @param int $start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data (page 0)
420	* @param int $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=1000)
421	* @return array an array containing a count of all matching campaigns and the specific ones for the current page (see Returned Fields for description)
422	* @returnf int total the total number of campaigns matching the filters passed in
423	* @returnf array data the data for each campaign being returned
424	string id Campaign Id (used for all other campaign functions)
425	int web_id The Campaign id used in our web app, allows you to create a link directly to it
426	string list_id The List used for this campaign
427	int folder_id The Folder this campaign is in
428	int template_id The Template this campaign uses
429	string content_type How the campaign's content is put together - one of 'template', 'html', 'url'
430	string title Title of the campaign
431	string type The type of campaign this is (regular,plaintext,absplit,rss,inspection,trans,auto)
432	string create_time Creation time for the campaign
433	string send_time Send time for the campaign - also the scheduled time for scheduled campaigns.
434	int emails_sent Number of emails email was sent to
435	string status Status of the given campaign (save,paused,schedule,sending,sent)
436	string from_name From name of the given campaign
437	string from_email Reply-to email of the given campaign
438	string subject Subject of the given campaign
439	string to_name Custom "To:" email string using merge variables
440	string archive_url Archive link for the given campaign
441	boolean inline_css Whether or not the campaign content's css was auto-inlined
442	string analytics Either "google" if enabled or "N" if disabled
443	string analytics_tag The name/tag the campaign's links were tagged with if analytics were enabled.
444	boolean authenticate Whether or not the campaign was authenticated
445	boolean ecomm360 Whether or not ecomm360 tracking was appended to links
446	boolean auto_tweet Whether or not the campaign was auto tweeted after sending
447	string auto_fb_post A comma delimited list of Facebook Profile/Page Ids the campaign was posted to after sending. If not used, blank.
448	boolean auto_footer Whether or not the auto_footer was manually turned on
449	boolean timewarp Whether or not the campaign used Timewarp
450	boolean timewarp_schedule The time, in GMT, that the Timewarp campaign is being sent. For A/B Split campaigns, this is blank and is instead in their schedule_a and schedule_b in the type_opts array
451	array tracking containing "text_clicks", "html_clicks", and "opens" as boolean values representing whether or not they were enabled
452	string segment_text a string marked-up with HTML explaining the segment used for the campaign in plain English
453	array segment_opts the segment used for the campaign - can be passed to campaignSegmentTest() or campaignCreate()
454	array type_opts the type-specific options for the campaign - can be passed to campaignCreate()
455	*/
456	function campaigns($filters=array (
457	), $start=0, $limit=25) {
458	$params = array();
459	$params["filters"] = $filters;
460	$params["start"] = $start;
461	$params["limit"] = $limit;
462	return $this->callServer("campaigns", $params);
463	}
464
465	/**
466	* Given a list and a campaign, get all the relevant campaign statistics (opens, bounces, clicks, etc.)
467	*
468	* @section Campaign Stats
469	*
470	* @example mcapi_campaignStats.php
471	* @example xml-rpc_campaignStats.php
472	*
473	* @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
474	* @return array struct of the statistics for this campaign
475	* @returnf int syntax_errors Number of email addresses in campaign that had syntactical errors.
476	* @returnf int hard_bounces Number of email addresses in campaign that hard bounced.
477	* @returnf int soft_bounces Number of email addresses in campaign that soft bounced.
478	* @returnf int unsubscribes Number of email addresses in campaign that unsubscribed.
479	* @returnf int abuse_reports Number of email addresses in campaign that reported campaign for abuse.
480	* @returnf int forwards Number of times email was forwarded to a friend.
481	* @returnf int forwards_opens Number of times a forwarded email was opened.
482	* @returnf int opens Number of times the campaign was opened.
483	* @returnf date last_open Date of the last time the email was opened.
484	* @returnf int unique_opens Number of people who opened the campaign.
485	* @returnf int clicks Number of times a link in the campaign was clicked.
486	* @returnf int unique_clicks Number of unique recipient/click pairs for the campaign.
487	* @returnf date last_click Date of the last time a link in the email was clicked.
488	* @returnf int users_who_clicked Number of unique recipients who clicked on a link in the campaign.
489	* @returnf int emails_sent Number of email addresses campaign was sent to.
490	* @returnf array absplit If this was an absplit campaign, stats for the A and B groups will be returned
491	int bounces_a bounces for the A group
492	int bounces_b bounces for the B group
493	int forwards_a forwards for the A group
494	int forwards_b forwards for the B group
495	int abuse_reports_a abuse reports for the A group
496	int abuse_reports_b abuse reports for the B group
497	int unsubs_a unsubs for the A group
498	int unsubs_b unsubs for the B group
499	int recipients_click_a clicks for the A group
500	int recipients_click_b clicks for the B group
501	int forwards_opens_a opened forwards for the A group
502	int forwards_opens_b opened forwards for the A group
503	* @returnf array timewarp If this campaign was a Timewarp campaign, an array of stats from each timezone for it, with the GMT offset as they key. Each timezone will contain:
504	int opens opens for this timezone
505	string last_open the date/time of the last open for this timezone
506	int unique_opens the unique opens for this timezone
507	int clicks the total clicks for this timezone
508	string last_click the date/time of the last click for this timezone
509	int unique_opens the unique clicks for this timezone
510	int bounces the total bounces for this timezone
511	int total the total number of members sent to in this timezone
512	int sent the total number of members delivered to in this timezone
513	*/
514	function campaignStats($cid) {
515	$params = array();
516	$params["cid"] = $cid;
517	return $this->callServer("campaignStats", $params);
518	}
519
520	/**
521	* Get an array of the urls being tracked, and their click counts for a given campaign
522	*
523	* @section Campaign Stats
524	*
525	* @example mcapi_campaignClickStats.php
526	* @example xml-rpc_campaignClickStats.php
527	*
528	* @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
529	* @return struct urls will be keys and contain their associated statistics:
530	* @returnf int clicks Number of times the specific link was clicked
531	* @returnf int unique Number of unique people who clicked on the specific link
532	*/
533	function campaignClickStats($cid) {
534	$params = array();
535	$params["cid"] = $cid;
536	return $this->callServer("campaignClickStats", $params);
537	}
538
539	/**
540	* Get the top 5 performing email domains for this campaign. Users want more than 5 should use campaign campaignEmailStatsAIM()
541	* or campaignEmailStatsAIMAll() and generate any additional stats they require.
542	*
543	* @section Campaign Stats
544	*
545	* @example mcapi_campaignEmailDomainPerformance.php
546	*
547	* @param string $cid the campaign id to pull email domain performance for (can be gathered using campaigns())
548	* @return array domains email domains and their associated stats
549	* @returnf string domain Domain name or special "Other" to roll-up stats past 5 domains
550	* @returnf int total_sent Total Email across all domains - this will be the same in every row
551	* @returnf int emails Number of emails sent to this domain
552	* @returnf int bounces Number of bounces
553	* @returnf int opens Number of opens
554	* @returnf int clicks Number of clicks
555	* @returnf int unsubs Number of unsubs
556	* @returnf int delivered Number of deliveries
557	* @returnf int emails_pct Percentage of emails that went to this domain (whole number)
558	* @returnf int bounces_pct Percentage of bounces from this domain (whole number)
559	* @returnf int opens_pct Percentage of opens from this domain (whole number)
560	* @returnf int clicks_pct Percentage of clicks from this domain (whole number)
561	* @returnf int unsubs_pct Percentage of unsubs from this domain (whole number)
562	*/
563	function campaignEmailDomainPerformance($cid) {
564	$params = array();
565	$params["cid"] = $cid;
566	return $this->callServer("campaignEmailDomainPerformance", $params);
567	}
568
569	/**
570	* Get all email addresses the campaign was successfully sent to (ie, no bounces)
571	*
572	* @section Campaign Stats
573	*
574	* @param string $cid the campaign id to pull members for (can be gathered using campaigns())
575	* @param string $status optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
576	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
577	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
578	* @return array a total of all matching emails and the specific emails for this page
579	* @returnf int total the total number of members for the campaign and status
580	* @returnf array data the full campaign member records
581	string email the email address sent to
582	string status the status of the send - one of 'sent', 'hard', 'soft'
583	string absplit_group if this was an absplit campaign, one of 'a','b', or 'winner'
584	string tz_group if this was an timewarp campaign the timezone GMT offset the member was included in
585	*/
586	function campaignMembers($cid, $status=NULL, $start=0, $limit=1000) {
587	$params = array();
588	$params["cid"] = $cid;
589	$params["status"] = $status;
590	$params["start"] = $start;
591	$params["limit"] = $limit;
592	return $this->callServer("campaignMembers", $params);
593	}
594
595	/**
596	* <strong>DEPRECATED</strong> Get all email addresses with Hard Bounces for a given campaign
597	*
598	* @deprecated See campaignMembers() for a replacement
599	*
600	* @section Campaign Stats
601	*
602	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
603	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
604	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
605	* @return array a total of all hard bounced emails and the specific emails for this page
606	* @returnf int total the total number of hard bounces for the campaign
607	* @returnf array data the full email addresses that bounced
608	string email the email address that bounced
609	*/
610	function campaignHardBounces($cid, $start=0, $limit=1000) {
611	$params = array();
612	$params["cid"] = $cid;
613	$params["start"] = $start;
614	$params["limit"] = $limit;
615	return $this->callServer("campaignHardBounces", $params);
616	}
617
618	/**
619	* <strong>DEPRECATED</strong> Get all email addresses with Soft Bounces for a given campaign
620	*
621	* @deprecated See campaignMembers() for a replacement
622	*
623	* @section Campaign Stats
624	*
625	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
626	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
627	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
628	* @return array a total of all soft bounced emails and the specific emails for this page
629	* @returnf int total the total number of soft bounces for the campaign
630	* @returnf array data the full email addresses that bounced
631	string email the email address that bounced
632	*/
633	function campaignSoftBounces($cid, $start=0, $limit=1000) {
634	$params = array();
635	$params["cid"] = $cid;
636	$params["start"] = $start;
637	$params["limit"] = $limit;
638	return $this->callServer("campaignSoftBounces", $params);
639	}
640
641	/**
642	* Get all unsubscribed email addresses for a given campaign
643	*
644	* @section Campaign Stats
645	*
646	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
647	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
648	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
649	* @return array email addresses that unsubscribed from this campaign along with reasons, if given
650	* @return array a total of all unsubscribed emails and the specific emails for this page
651	* @returnf int total the total number of unsubscribes for the campaign
652	* @returnf array data the full email addresses that unsubscribed
653	string email the email address that unsubscribed
654	string reason For unsubscribes only - the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
655	string reason_text For unsubscribes only - if the reason is OTHER, the text entered.
656	*/
657	function campaignUnsubscribes($cid, $start=0, $limit=1000) {
658	$params = array();
659	$params["cid"] = $cid;
660	$params["start"] = $start;
661	$params["limit"] = $limit;
662	return $this->callServer("campaignUnsubscribes", $params);
663	}
664
665	/**
666	* Get all email addresses that complained about a given campaign
667	*
668	* @section Campaign Stats
669	*
670	* @example mcapi_campaignAbuseReports.php
671	*
672	* @param string $cid the campaign id to pull abuse reports for (can be gathered using campaigns())
673	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
674	* @param int $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
675	* @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
676	* @return array reports the abuse reports for this campaign
677	* @returnf string date date/time the abuse report was received and processed
678	* @returnf string email the email address that reported abuse
679	* @returnf string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
680	*/
681	function campaignAbuseReports($cid, $since=NULL, $start=0, $limit=500) {
682	$params = array();
683	$params["cid"] = $cid;
684	$params["since"] = $since;
685	$params["start"] = $start;
686	$params["limit"] = $limit;
687	return $this->callServer("campaignAbuseReports", $params);
688	}
689
690	/**
691	* Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
692	* suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
693	*
694	* @section Campaign Stats
695	*
696	* @example mcapi_campaignAdvice.php
697	*
698	* @param string $cid the campaign id to pull advice text for (can be gathered using campaigns())
699	* @return array advice on the campaign's performance
700	* @returnf msg the advice message
701	* @returnf type the "type" of the message. one of: negative, positive, or neutral
702	*/
703	function campaignAdvice($cid) {
704	$params = array();
705	$params["cid"] = $cid;
706	return $this->callServer("campaignAdvice", $params);
707	}
708
709	/**
710	* Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
711	*
712	* @section Campaign Stats
713	*
714	* @example mcapi_campaignAnalytics.php
715	*
716	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
717	* @return array analytics we've collected for the passed campaign.
718	* @returnf int visits number of visits
719	* @returnf int pages number of page views
720	* @returnf int new_visits new visits recorded
721	* @returnf int bounces vistors who "bounced" from your site
722	* @returnf double time_on_site the total time visitors spent on your sites
723	* @returnf int goal_conversions number of goals converted
724	* @returnf double goal_value value of conversion in dollars
725	* @returnf double revenue revenue generated by campaign
726	* @returnf int transactions number of transactions tracked
727	* @returnf int ecomm_conversions number Ecommerce transactions tracked
728	* @returnf array goals an array containing goal names and number of conversions
729	*/
730	function campaignAnalytics($cid) {
731	$params = array();
732	$params["cid"] = $cid;
733	return $this->callServer("campaignAnalytics", $params);
734	}
735
736	/**
737	* Retrieve the countries and number of opens tracked for each. Email address are not returned.
738	*
739	* @section Campaign Stats
740	*
741	*
742	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
743	* @return array countries an array of countries where opens occurred
744	* @returnf string code The ISO3166 2 digit country code
745	* @returnf string name A version of the country name, if we have it
746	* @returnf int opens The total number of opens that occurred in the country
747	* @returnf bool region_detail Whether or not a subsequent call to campaignGeoOpensByCountry() will return anything
748	*/
749	function campaignGeoOpens($cid) {
750	$params = array();
751	$params["cid"] = $cid;
752	return $this->callServer("campaignGeoOpens", $params);
753	}
754
755	/**
756	* Retrieve the regions and number of opens tracked for a certain country. Email address are not returned.
757	*
758	* @section Campaign Stats
759	*
760	*
761	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
762	* @param string $code An ISO3166 2 digit country code
763	* @return array regions an array of regions within the provided country where opens occurred.
764	* @returnf string code An internal code for the region. When this is blank, it indicates we know the country, but not the region
765	* @returnf string name The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
766	* @returnf int opens The total number of opens that occurred in the country
767	*/
768	function campaignGeoOpensForCountry($cid, $code) {
769	$params = array();
770	$params["cid"] = $cid;
771	$params["code"] = $code;
772	return $this->callServer("campaignGeoOpensForCountry", $params);
773	}
774
775	/**
776	* Retrieve the tracked eepurl mentions on Twitter
777	*
778	* @section Campaign Stats
779	*
780	*
781	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
782	* @return array stats an array containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
783	* @returnf array twitter various Twitter related stats
784	int tweets Total number of tweets seen
785	string first_tweet date and time of the first tweet seen
786	string last_tweet date and time of the last tweet seen
787	int retweets Total number of retweets seen
788	string first_retweet date and time of the first retweet seen
789	string last_retweet date and time of the last retweet seen
790	array statuses an array of statuses recorded inclduing the status, screen_name, status_id, and datetime fields plus an is_retweet flag
791	* @returnf array clicks stats related to click-throughs on the eepurl
792	int clicks Total number of clicks seen
793	string first_click date and time of the first click seen
794	string last_click date and time of the first click seen
795	array locations an array of geographic locations including country, region, and total clicks
796	* @returnf array referrers an array of arrays, each containing
797	string referrer the referrer, truncated to 100 bytes
798	int clicks Total number of clicks seen from this referrer
799	string first_click date and time of the first click seen from this referrer
800	string last_click date and time of the first click seen from this referrer
801	*/
802	function campaignEepUrlStats($cid) {
803	$params = array();
804	$params["cid"] = $cid;
805	return $this->callServer("campaignEepUrlStats", $params);
806	}
807
808	/**
809	* Retrieve the most recent full bounce message for a specific email address on the given campaign.
810	* Messages over 30 days old are subject to being removed
811	*
812	*
813	* @section Campaign Stats
814	*
815	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
816	* @param string $email the email address or unique id of the member to pull a bounce message for.
817	* @return array the full bounce message for this email+campaign along with some extra data.
818	* @returnf string date date/time the bounce was received and processed
819	* @returnf string email the email address that bounced
820	* @returnf string message the entire bounce message received
821	*/
822	function campaignBounceMessage($cid, $email) {
823	$params = array();
824	$params["cid"] = $cid;
825	$params["email"] = $email;
826	return $this->callServer("campaignBounceMessage", $params);
827	}
828
829	/**
830	* Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
831	* of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
832	* message over 30 days old are subject to being removed
833	*
834	* @section Campaign Stats
835	*
836	* @example mcapi_campaignBounceMessages.php
837	*
838	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
839	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
840	* @param int $limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 50
841	* @param string $since optional pull only messages since this time - use YYYY-MM-DD format in <strong>GMT</strong> (we only store the date, not the time)
842	* @return array bounces the full bounce messages for this campaign
843	* @returnf int total that total number of bounce messages for the campaign
844	* @returnf array data an array containing the data for this page
845	string date date/time the bounce was received and processed
846	string email the email address that bounced
847	string message the entire bounce message received
848	*/
849	function campaignBounceMessages($cid, $start=0, $limit=25, $since=NULL) {
850	$params = array();
851	$params["cid"] = $cid;
852	$params["start"] = $start;
853	$params["limit"] = $limit;
854	$params["since"] = $since;
855	return $this->callServer("campaignBounceMessages", $params);
856	}
857
858	/**
859	* Retrieve the Ecommerce Orders tracked by campaignEcommOrderAdd()
860	*
861	* @section Campaign Stats
862	*
863	* @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
864	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
865	* @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
866	* @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
867	* @return array the total matching orders and the specific orders for the requested page
868	* @returnf int total the total matching orders
869	* @returnf array data the actual data for each order being returned
870	string store_id the store id generated by the plugin used to uniquely identify a store
871	string store_name the store name collected by the plugin - often the domain name
872	string order_id the internal order id the store tracked this order by
873	string email the email address that received this campaign and is associated with this order
874	double order_total the order total
875	double tax_total the total tax for the order (if collected)
876	double ship_total the shipping total for the order (if collected)
877	string order_date the date the order was tracked - from the store if possible, otherwise the GMT time we recieved it
878	array lines containing detail of the order - product, category, quantity, item cost
879	*/
880	function campaignEcommOrders($cid, $start=0, $limit=100, $since=NULL) {
881	$params = array();
882	$params["cid"] = $cid;
883	$params["start"] = $start;
884	$params["limit"] = $limit;
885	$params["since"] = $since;
886	return $this->callServer("campaignEcommOrders", $params);
887	}
888
889	/**
890	* Get the URL to a customized <a href="http://eepurl.com/gKmL" target="_blank">VIP Report</a> for the specified campaign and optionally send an email to someone with links to it. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)
891	*
892	* @section Campaign Related
893	*
894	* @param string $cid the campaign id to share a report for (can be gathered using campaigns())
895	* @param array $opts optional various parameters which can be used to configure the shared report
896	string header_type optional - "text" or "image', defaults to "text'
897	string header_data optional - if "header_type" is text, the text to display. if "header_type" is "image" a valid URL to an image file. Note that images will be resized to be no more than 500x150. Defaults to the Accounts Company Name.
898	boolean secure optional - whether to require a password for the shared report. defaults to "true"
899	string password optional - if secure is true and a password is not included, we will generate one. It is always returned.
900	string to_email optional - optional, email address to share the report with - no value means an email will not be sent
901	array theme optional - an array containing either 3 or 6 character color code values for: "bg_color", "header_color", "current_tab", "current_tab_text", "normal_tab", "normal_tab_text", "hover_tab", "hover_tab_text"
902	string css_url optional - a link to an external CSS file to be included after our default CSS (http://vip-reports.net/css/vip.css) <strong>only if</strong> loaded via the "secure_url" - max 255 bytes
903	* @return struct Struct containing details for the shared report
904	* @returnf string title The Title of the Campaign being shared
905	* @returnf string url The URL to the shared report
906	* @returnf string secure_url The URL to the shared report, including the password (good for loading in an IFRAME). For non-secure reports, this will not be returned
907	* @returnf string password If secured, the password for the report, otherwise this field will not be returned
908	*/
909	function campaignShareReport($cid, $opts=array (
910	)) {
911	$params = array();
912	$params["cid"] = $cid;
913	$params["opts"] = $opts;
914	return $this->callServer("campaignShareReport", $params);
915	}
916
917	/**
918	* Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content
919	*
920	* @section Campaign Related
921	*
922	* @param string $cid the campaign id to get content for (can be gathered using campaigns())
923	* @param bool $for_archive optional controls whether we return the Archive version (true) or the Raw version (false), defaults to true
924	* @return struct Struct containing all content for the campaign (see Returned Fields for details
925	* @returnf string html The HTML content used for the campgain with merge tags intact
926	* @returnf string text The Text content used for the campgain with merge tags intact
927	*/
928	function campaignContent($cid, $for_archive=true) {
929	$params = array();
930	$params["cid"] = $cid;
931	$params["for_archive"] = $for_archive;
932	return $this->callServer("campaignContent", $params);
933	}
934
935	/**
936	* Get the HTML template content sections for a campaign. Note that this <strong>will</strong> return very jagged, non-standard results based on the template
937	* a campaign is using. You only want to use this if you want to allow editing template sections in your applicaton.
938	*
939	* @section Campaign Related
940	*
941	* @param string $cid the campaign id to get content for (can be gathered using campaigns())
942	* @return array array containing all content section for the campaign -
943	*/
944	function campaignTemplateContent($cid) {
945	$params = array();
946	$params["cid"] = $cid;
947	return $this->callServer("campaignTemplateContent", $params);
948	}
949
950	/**
951	* Retrieve the list of email addresses that opened a given campaign with how many times they opened - note: this AIM function is free and does
952	* not actually require the AIM module to be installed
953	*
954	* @section Campaign Report Data
955	*
956	* @param string $cid the campaign id to get opens for (can be gathered using campaigns())
957	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
958	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
959	* @return array array containing the total records matched and the specific records for this page
960	* @returnf int total the total number of records matched
961	* @returnf array data the actual opens data, including:
962	string email Email address that opened the campaign
963	int open_count Total number of times the campaign was opened by this email address
964	*/
965	function campaignOpenedAIM($cid, $start=0, $limit=1000) {
966	$params = array();
967	$params["cid"] = $cid;
968	$params["start"] = $start;
969	$params["limit"] = $limit;
970	return $this->callServer("campaignOpenedAIM", $params);
971	}
972
973	/**
974	* Retrieve the list of email addresses that did not open a given campaign
975	*
976	* @section Campaign Report Data
977	*
978	* @param string $cid the campaign id to get no opens for (can be gathered using campaigns())
979	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
980	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
981	* @return array array containing the total records matched and the specific records for this page
982	* @returnf int total the total number of records matched
983	* @returnf array data the email addresses that did not open the campaign
984	string email Email address that opened the campaign
985	*/
986	function campaignNotOpenedAIM($cid, $start=0, $limit=1000) {
987	$params = array();
988	$params["cid"] = $cid;
989	$params["start"] = $start;
990	$params["limit"] = $limit;
991	return $this->callServer("campaignNotOpenedAIM", $params);
992	}
993
994	/**
995	* Return the list of email addresses that clicked on a given url, and how many times they clicked
996	*
997	* @section Campaign Report Data
998	*
999	* @param string $cid the campaign id to get click stats for (can be gathered using campaigns())
1000	* @param string $url the URL of the link that was clicked on
1001	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1002	* @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
1003	* @return array array containing the total records matched and the specific records for this page
1004	* @returnf int total the total number of records matched
1005	* @returnf array data the email addresses that did not open the campaign
1006	string email Email address that opened the campaign
1007	int clicks Total number of times the URL was clicked on by this email address
1008	*/
1009	function campaignClickDetailAIM($cid, $url, $start=0, $limit=1000) {
1010	$params = array();
1011	$params["cid"] = $cid;
1012	$params["url"] = $url;
1013	$params["start"] = $start;
1014	$params["limit"] = $limit;
1015	return $this->callServer("campaignClickDetailAIM", $params);
1016	}
1017
1018	/**
1019	* Given a campaign and email address, return the entire click and open history with timestamps, ordered by time
1020	*
1021	* @section Campaign Report Data
1022	*
1023	* @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1024	* @param array $email_address an array of up to 50 email addresses to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns. For backwards compatibility, if a string is passed, it will be treated as an array with a single element (will not work with XML-RPC).
1025	* @return array an array with the keys listed in Returned Fields below
1026	* @returnf int success the number of email address records found
1027	* @returnf int error the number of email address records which could not be found
1028	* @returnf array data arrays containing the actions (opens and clicks) that the email took, with timestamps
1029	string action The action taken (open or click)
1030	string timestamp Time the action occurred
1031	string url For clicks, the URL that was clicked
1032	*/
1033	function campaignEmailStatsAIM($cid, $email_address) {
1034	$params = array();
1035	$params["cid"] = $cid;
1036	$params["email_address"] = $email_address;
1037	return $this->callServer("campaignEmailStatsAIM", $params);
1038	}
1039
1040	/**
1041	* Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
1042	* for every user a campaign was delivered to.
1043	*
1044	* @section Campaign Report Data
1045	* @example mcapi_campaignEmailStatsAIMAll.php
1046	*
1047	* @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1048	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1049	* @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 1000
1050	* @return array Array containing a total record count and data including the actions (opens and clicks) for each email, with timestamps
1051	* @returnf int total the total number of records
1052	* @returnf array data each record with their details:
1053	string action The action taken (open or click)
1054	string timestamp Time the action occurred
1055	string url For clicks, the URL that was clicked
1056	*/
1057	function campaignEmailStatsAIMAll($cid, $start=0, $limit=100) {
1058	$params = array();
1059	$params["cid"] = $cid;
1060	$params["start"] = $start;
1061	$params["limit"] = $limit;
1062	return $this->callServer("campaignEmailStatsAIMAll", $params);
1063	}
1064
1065	/**
1066	* Attach Ecommerce Order Information to a Campaign. This will generall be used by ecommerce package plugins
1067	* <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
1068	* @section Campaign Related
1069	*
1070	* @param array $order an array of information pertaining to the order that has completed. Use the following keys:
1071	string id the Order Id
1072	string campaign_id the Campaign Id to track this order with (see the "mc_cid" query string variable a campaign passes)
1073	string email_id the Email Id of the subscriber we should attach this order to (see the "mc_eid" query string variable a campaign passes)
1074	double total The Order Total (ie, the full amount the customer ends up paying)
1075	string order_date optional the date of the order - if this is not provided, we will default the date to now
1076	double shipping optional the total paid for Shipping Fees
1077	double tax optional the total tax paid
1078	string store_id a unique id for the store sending the order in (20 bytes max)
1079	string store_name optional a "nice" name for the store - typically the base web address (ie, "store.mailchimp.com"). We will automatically update this if it changes (based on store_id)
1080	string plugin_id the MailChimp assigned Plugin Id. Get yours by <a href="/register.php">registering here</a>
1081	array items the individual line items for an order using these keys:
1082	<div style="padding-left:30px"><table><tr><td colspan=*>
1083	int line_num optional the line number of the item on the order. We will generate these if they are not passed
1084	int product_id the store's internal Id for the product. Lines that do no contain this will be skipped
1085	string product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
1086	int category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
1087	string category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
1088	double qty the quantity of the item ordered
1089	double cost the cost of a single item (ie, not the extended cost of the line)
1090	</td></tr></table></div>
1091	* @return bool true if the data is saved, otherwise an error is thrown.
1092	*/
1093	function campaignEcommOrderAdd($order) {
1094	$params = array();
1095	$params["order"] = $order;
1096	return $this->callServer("campaignEcommOrderAdd", $params);
1097	}
1098
1099	/**
1100	* Retrieve all of the lists defined for your user account
1101	*
1102	* @section List Related
1103	* @example mcapi_lists.php
1104	* @example xml-rpc_lists.php
1105	*
1106	* @param array $filters a hash of filters to apply to this query - all are optional:
1107	string list_id optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching
1108	string list_name optional - only lists that match this name
1109	string from_name optional - only lists that have a default from name matching this
1110	string from_email optional - only lists that have a default from email matching this
1111	string from_subject optional - only lists that have a default from email matching this
1112	string created_before optional - only show lists that were created before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
1113	string created_after optional - only show lists that were created since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
1114	boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true
1115	* @param int $start optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
1116	* @param int $limit optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)
1117	* @return array an array with keys listed in Returned Fields below
1118	* @returnf int total the total number of lists which matched the provided filters
1119	* @returnf array data the lists which matched the provided filters, including the following for
1120	string id The list id for this list. This will be used for all other list management functions.
1121	int web_id The list id used in our web app, allows you to create a link directly to it
1122	string name The name of the list.
1123	string date_created The date that this list was created.
1124	boolean email_type_option Whether or not the List supports multiple formats for emails or just HTML
1125	boolean use_awesomebar Whether or not campaigns for this list use the Awesome Bar in archives by default
1126	string default_from_name Default From Name for campaigns using this list
1127	string default_from_email Default From Email for campaigns using this list
1128	string default_subject Default Subject Line for campaigns using this list
1129	string default_language Default Language for this list's forms
1130	int list_rating An auto-generated activity score for the list (0 - 5)
1131	array stats various stats and counts for the list
1132	int member_count The number of active members in the given list.
1133	int unsubscribe_count The number of members who have unsubscribed from the given list.
1134	int cleaned_count The number of members cleaned from the given list.
1135	int member_count_since_send The number of active members in the given list since the last campaign was sent
1136	int unsubscribe_count_since_send The number of members who have unsubscribed from the given list since the last campaign was sent
1137	int cleaned_count_since_send The number of members cleaned from the given list since the last campaign was sent
1138	int campaign_count The number of campaigns in any status that use this list
1139	int grouping_count The number of Interest Groupings for this list
1140	int group_count The number of Interest Groups (regardless of grouping) for this list
1141	int merge_var_count The number of merge vars for this list (not including the required EMAIL one)
1142	int avg_sub_rate the average number of subscribe per month for the list (empty value if we haven't calculated this yet)
1143	int avg_unsub_rate the average number of unsubscribe per month for the list (empty value if we haven't calculated this yet)
1144	int target_sub_rate the target subscription rate for the list to keep it growing (empty value if we haven't calculated this yet)
1145	int open_rate the average open rate per campaign for the list (empty value if we haven't calculated this yet)
1146	int click_rate the average click rate per campaign for the list (empty value if we haven't calculated this yet)
1147	array modules Any list specific modules installed for this list (example is SocialPro)
1148	*/
1149	function lists($filters=array (
1150	), $start=0, $limit=25) {
1151	$params = array();
1152	$params["filters"] = $filters;
1153	$params["start"] = $start;
1154	$params["limit"] = $limit;
1155	return $this->callServer("lists", $params);
1156	}
1157
1158	/**
1159	* Get the list of merge tags for a given list, including their name, tag, and required setting
1160	*
1161	* @section List Related
1162	* @example xml-rpc_listMergeVars.php
1163	*
1164	* @param string $id the list id to connect to. Get by calling lists()
1165	* @return array list of merge tags for the list
1166	* @returnf string name Name of the merge field
1167	* @returnf bool req Denotes whether the field is required (true) or not (false)
1168	* @returnf string field_type The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl
1169	* @returnf bool public Whether or not this field is visible to list subscribers
1170	* @returnf bool show Whether the list owner has this field displayed on their list dashboard
1171	* @returnf string order The order the list owner has set this field to display in
1172	* @returnf string default The default value the list owner has set for this field
1173	* @returnf string size The width of the field to be used
1174	* @returnf string tag The merge tag that's used for forms and listSubscribe() and listUpdateMember()
1175	* @returnf array choices For radio and dropdown field types, an array of the options available
1176	*/
1177	function listMergeVars($id) {
1178	$params = array();
1179	$params["id"] = $id;
1180	return $this->callServer("listMergeVars", $params);
1181	}
1182
1183	/**
1184	* Add a new merge tag to a given list
1185	*
1186	* @section List Related
1187	* @example xml-rpc_listMergeVarAdd.php
1188	*
1189	* @param string $id the list id to connect to. Get by calling lists()
1190	* @param string $tag The merge tag to add, e.g. FNAME
1191	* @param string $name The long description of the tag being added, used for user displays
1192	* @param array $options optional Various options for this merge var. <em>note:</em> for historical purposes this can also take a "boolean"
1193	string field_type optional one of: text, number, radio, dropdown, date, address, phone, url, imageurl - defaults to text
1194	boolean req optional indicates whether the field is required - defaults to false
1195	boolean public optional indicates whether the field is displayed in public - defaults to true
1196	boolean show optional indicates whether the field is displayed in the app's list member view - defaults to true
1197	string default_value optional the default value for the field. See listSubscribe() for formatting info. Defaults to blank
1198	array choices optional kind of - an array of strings to use as the choices for radio and dropdown type fields
1199
1200	* @return bool true if the request succeeds, otherwise an error will be thrown
1201	*/
1202	function listMergeVarAdd($id, $tag, $name, $options=array (
1203	)) {
1204	$params = array();
1205	$params["id"] = $id;
1206	$params["tag"] = $tag;
1207	$params["name"] = $name;
1208	$params["options"] = $options;
1209	return $this->callServer("listMergeVarAdd", $params);
1210	}
1211
1212	/**
1213	* Update most parameters for a merge tag on a given list. You cannot currently change the merge type
1214	*
1215	* @section List Related
1216	*
1217	* @param string $id the list id to connect to. Get by calling lists()
1218	* @param string $tag The merge tag to update
1219	* @param array $options The options to change for a merge var. See listMergeVarAdd() for valid options
1220	* @return bool true if the request succeeds, otherwise an error will be thrown
1221	*/
1222	function listMergeVarUpdate($id, $tag, $options) {
1223	$params = array();
1224	$params["id"] = $id;
1225	$params["tag"] = $tag;
1226	$params["options"] = $options;
1227	return $this->callServer("listMergeVarUpdate", $params);
1228	}
1229
1230	/**
1231	* Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well!
1232	* Note that on large lists this method may seem a bit slower than calls you typically make.
1233	*
1234	* @section List Related
1235	* @example xml-rpc_listMergeVarDel.php
1236	*
1237	* @param string $id the list id to connect to. Get by calling lists()
1238	* @param string $tag The merge tag to delete
1239	* @return bool true if the request succeeds, otherwise an error will be thrown
1240	*/
1241	function listMergeVarDel($id, $tag) {
1242	$params = array();
1243	$params["id"] = $id;
1244	$params["tag"] = $tag;
1245	return $this->callServer("listMergeVarDel", $params);
1246	}
1247
1248	/**
1249	* Get the list of interest groupings for a given list, including the label, form information, and included groups for each
1250	*
1251	* @section List Related
1252	* @example xml-rpc_listInterestGroupings.php
1253	*
1254	* @param string $id the list id to connect to. Get by calling lists()
1255	* @return struct list of interest groups for the list
1256	* @returnf string id The id for the Grouping
1257	* @returnf string name Name for the Interest groups
1258	* @returnf string form_field Gives the type of interest group: checkbox,radio,select
1259	* @returnf array groups Array of the grouping options including the "bit" value, "name", "display_order", and number of "subscribers" with the option selected.
1260	*/
1261	function listInterestGroupings($id) {
1262	$params = array();
1263	$params["id"] = $id;
1264	return $this->callServer("listInterestGroupings", $params);
1265	}
1266
1267	/** Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first
1268	* group will automatically turn them on.
1269	*
1270	* @section List Related
1271	* @example xml-rpc_listInterestGroupAdd.php
1272	*
1273	* @param string $id the list id to connect to. Get by calling lists()
1274	* @param string $group_name the interest group to add - group names must be unique within a grouping
1275	* @param int optional $grouping_id The grouping to add the new group to - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
1276	* @return bool true if the request succeeds, otherwise an error will be thrown
1277	*/
1278	function listInterestGroupAdd($id, $group_name, $grouping_id=NULL) {
1279	$params = array();
1280	$params["id"] = $id;
1281	$params["group_name"] = $group_name;
1282	$params["grouping_id"] = $grouping_id;
1283	return $this->callServer("listInterestGroupAdd", $params);
1284	}
1285
1286	/** Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.
1287	*
1288	* @section List Related
1289	* @example xml-rpc_listInterestGroupDel.php
1290	*
1291	* @param string $id the list id to connect to. Get by calling lists()
1292	* @param string $group_name the interest group to delete
1293	* @param int $grouping_id The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
1294	* @return bool true if the request succeeds, otherwise an error will be thrown
1295	*/
1296	function listInterestGroupDel($id, $group_name, $grouping_id=NULL) {
1297	$params = array();
1298	$params["id"] = $id;
1299	$params["group_name"] = $group_name;
1300	$params["grouping_id"] = $grouping_id;
1301	return $this->callServer("listInterestGroupDel", $params);
1302	}
1303
1304	/** Change the name of an Interest Group
1305	*
1306	* @section List Related
1307	*
1308	* @param string $id the list id to connect to. Get by calling lists()
1309	* @param string $old_name the interest group name to be changed
1310	* @param string $new_name the new interest group name to be set
1311	* @param int optional $grouping_id The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.
1312	* @return bool true if the request succeeds, otherwise an error will be thrown
1313	*/
1314	function listInterestGroupUpdate($id, $old_name, $new_name, $grouping_id=NULL) {
1315	$params = array();
1316	$params["id"] = $id;
1317	$params["old_name"] = $old_name;
1318	$params["new_name"] = $new_name;
1319	$params["grouping_id"] = $grouping_id;
1320	return $this->callServer("listInterestGroupUpdate", $params);
1321	}
1322
1323	/** Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first
1324	* grouping will automatically turn them on.
1325	*
1326	* @section List Related
1327	* @example xml-rpc_listInterestGroupingAdd.php
1328	*
1329	* @param string $id the list id to connect to. Get by calling lists()
1330	* @param string $name the interest grouping to add - grouping names must be unique
1331	* @param string $type The type of the grouping to add - one of "checkboxes", "hidden", "dropdown", "radio"
1332	* @param array $groups The lists of initial group names to be added - at least 1 is required and the names must be unique within a grouping. If the number takes you over the 60 group limit, an error will be thrown.
1333	* @return int the new grouping id if the request succeeds, otherwise an error will be thrown
1334	*/
1335	function listInterestGroupingAdd($id, $name, $type, $groups) {
1336	$params = array();
1337	$params["id"] = $id;
1338	$params["name"] = $name;
1339	$params["type"] = $type;
1340	$params["groups"] = $groups;
1341	return $this->callServer("listInterestGroupingAdd", $params);
1342	}
1343
1344	/** Update an existing Interest Grouping
1345	*
1346	* @section List Related
1347	* @example xml-rpc_listInterestGroupingUpdate.php
1348	*
1349	* @param int $grouping_id the interest grouping id - get from listInterestGroupings()
1350	* @param string $name The name of the field to update - either "name" or "type". Groups with in the grouping should be manipulated using the standard listInterestGroup* methods
1351	* @param string $value The new value of the field. Grouping names must be unique - only "hidden" and "checkboxes" grouping types can be converted between each other.
1352	* @return bool true if the request succeeds, otherwise an error will be thrown
1353	*/
1354	function listInterestGroupingUpdate($grouping_id, $name, $value) {
1355	$params = array();
1356	$params["grouping_id"] = $grouping_id;
1357	$params["name"] = $name;
1358	$params["value"] = $value;
1359	return $this->callServer("listInterestGroupingUpdate", $params);
1360	}
1361
1362	/** Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members
1363	*
1364	* @section List Related
1365	* @example xml-rpc_listInterestGroupingDel.php
1366	*
1367	* @param int $grouping_id the interest grouping id - get from listInterestGroupings()
1368	* @return bool true if the request succeeds, otherwise an error will be thrown
1369	*/
1370	function listInterestGroupingDel($grouping_id) {
1371	$params = array();
1372	$params["grouping_id"] = $grouping_id;
1373	return $this->callServer("listInterestGroupingDel", $params);
1374	}
1375
1376	/** Return the Webhooks configured for the given list
1377	*
1378	* @section List Related
1379	*
1380	* @param string $id the list id to connect to. Get by calling lists()
1381	* @return array list of webhooks
1382	* @returnf string url the URL for this Webhook
1383	* @returnf array actions the possible actions and whether they are enabled
1384	* @returnf array sources the possible sources and whether they are enabled
1385	*/
1386	function listWebhooks($id) {
1387	$params = array();
1388	$params["id"] = $id;
1389	return $this->callServer("listWebhooks", $params);
1390	}
1391
1392	/** Add a new Webhook URL for the given list
1393	*
1394	* @section List Related
1395	*
1396	* @param string $id the list id to connect to. Get by calling lists()
1397	* @param string $url a valid URL for the Webhook - it will be validated. note that a url may only exist on a list once.
1398	* @param array $actions optional a hash of actions to fire this Webhook for
1399	boolean subscribe optional as subscribes occur, defaults to true
1400	boolean unsubscribe optional as subscribes occur, defaults to true
1401	boolean profile optional as profile updates occur, defaults to true
1402	boolean cleaned optional as emails are cleaned from the list, defaults to true
1403	boolean upemail optional when subscribers change their email address, defaults to true
1404	* @param array $sources optional a hash of sources to fire this Webhook for
1405	boolean user optional user/subscriber initiated actions, defaults to true
1406	boolean admin optional admin actions in our web app, defaults to true
1407	boolean api optional actions that happen via API calls, defaults to false
1408	* @return bool true if the call succeeds, otherwise an exception will be thrown
1409	*/
1410	function listWebhookAdd($id, $url, $actions=array (
1411	), $sources=array (
1412	)) {
1413	$params = array();
1414	$params["id"] = $id;
1415	$params["url"] = $url;
1416	$params["actions"] = $actions;
1417	$params["sources"] = $sources;
1418	return $this->callServer("listWebhookAdd", $params);
1419	}
1420
1421	/** Delete an existing Webhook URL from a given list
1422	*
1423	* @section List Related
1424	*
1425	* @param string $id the list id to connect to. Get by calling lists()
1426	* @param string $url the URL of a Webhook on this list
1427	* @return boolean true if the call succeeds, otherwise an exception will be thrown
1428	*/
1429	function listWebhookDel($id, $url) {
1430	$params = array();
1431	$params["id"] = $id;
1432	$params["url"] = $url;
1433	return $this->callServer("listWebhookDel", $params);
1434	}
1435
1436	/** Retrieve all of the Static Segments for a list.
1437	*
1438	* @section List Related
1439	*
1440	* @param string $id the list id to connect to. Get by calling lists()
1441	* @return array an array of parameters for each static segment
1442	* @returnf int id the id of the segment
1443	* @returnf string name the name for the segment
1444	* @returnf int member_count the total number of members currently in a segment
1445	* @returnf date created_date the date/time the segment was created
1446	* @returnf date last_update the date/time the segment was last updated (add or del)
1447	* @returnf date last_reset the date/time the segment was last reset (ie had all members cleared from it)
1448	*/
1449	function listStaticSegments($id) {
1450	$params = array();
1451	$params["id"] = $id;
1452	return $this->callServer("listStaticSegments", $params);
1453	}
1454
1455	/** Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied
1456	* to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance.
1457	* When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation
1458	* options), though performance may degrade at that point.
1459	*
1460	* @section List Related
1461	*
1462	* @param string $id the list id to connect to. Get by calling lists()
1463	* @param string $name a unique name per list for the segment - 50 byte maximum length, anything longer will throw an error
1464	* @return int the id of the new segment, otherwise an error will be thrown.
1465	*/
1466	function listStaticSegmentAdd($id, $name) {
1467	$params = array();
1468	$params["id"] = $id;
1469	$params["name"] = $name;
1470	return $this->callServer("listStaticSegmentAdd", $params);
1471	}
1472
1473	/** Resets a static segment - removes <strong>all</strong> members from the static segment. Note: does not actually affect list member data
1474	*
1475	* @section List Related
1476	*
1477	* @param string $id the list id to connect to. Get by calling lists()
1478	* @param int $seg_id the id of the static segment to reset - get from listStaticSegments()
1479	* @return bool true if it worked, otherwise an error is thrown.
1480	*/
1481	function listStaticSegmentReset($id, $seg_id) {
1482	$params = array();
1483	$params["id"] = $id;
1484	$params["seg_id"] = $seg_id;
1485	return $this->callServer("listStaticSegmentReset", $params);
1486	}
1487
1488	/** Delete a static segment. Note that this will, of course, remove any member affiliations with the segment
1489	*
1490	* @section List Related
1491	*
1492	* @param string $id the list id to connect to. Get by calling lists()
1493	* @param int $seg_id the id of the static segment to delete - get from listStaticSegments()
1494	* @return bool true if it worked, otherwise an error is thrown.
1495	*/
1496	function listStaticSegmentDel($id, $seg_id) {
1497	$params = array();
1498	$params["id"] = $id;
1499	$params["seg_id"] = $seg_id;
1500	return $this->callServer("listStaticSegmentDel", $params);
1501	}
1502
1503	/** Add list members to a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list
1504	* in order to be included - this <strong>will not</strong> subscribe them to the list!
1505	*
1506	* @section List Related
1507	*
1508	* @param string $id the list id to connect to. Get by calling lists()
1509	* @param int $seg_id the id of the static segment to modify - get from listStaticSegments()
1510	* @param array $batch an array of email addresses and/or unique_ids to add to the segment
1511	* @return array an array with the results of the operation
1512	* @returnf int success the total number of successful updates (will include members already in the segment)
1513	* @returnf array errors the email address, an error code, and a message explaining why they couldn't be added
1514	*/
1515	function listStaticSegmentMembersAdd($id, $seg_id, $batch) {
1516	$params = array();
1517	$params["id"] = $id;
1518	$params["seg_id"] = $seg_id;
1519	$params["batch"] = $batch;
1520	return $this->callServer("listStaticSegmentMembersAdd", $params);
1521	}
1522
1523	/** Remove list members from a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list
1524	* in order to be removed - this <strong>will not</strong> unsubscribe them from the list!
1525	*
1526	* @section List Related
1527	*
1528	* @param string $id the list id to connect to. Get by calling lists()
1529	* @param int $seg_id the id of the static segment to delete - get from listStaticSegments()
1530	* @param array $batch an array of email addresses and/or unique_ids to remove from the segment
1531	* @return array an array with the results of the operation
1532	* @returnf int success the total number of succesful removals
1533	* @returnf array errors the email address, an error code, and a message explaining why they couldn't be removed
1534	*/
1535	function listStaticSegmentMembersDel($id, $seg_id, $batch) {
1536	$params = array();
1537	$params["id"] = $id;
1538	$params["seg_id"] = $seg_id;
1539	$params["batch"] = $batch;
1540	return $this->callServer("listStaticSegmentMembersDel", $params);
1541	}
1542
1543	/**
1544	* Subscribe the provided email to a list. By default this sends a confirmation email - you will not see new members until the link contained in it is clicked!
1545	*
1546	* @section List Related
1547	*
1548	* @example mcapi_listSubscribe.php
1549	* @example json_listSubscribe.php
1550	* @example xml-rpc_listSubscribe.php
1551	*
1552	* @param string $id the list id to connect to. Get by calling lists()
1553	* @param string $email_address the email address to subscribe
1554	* @param array $merge_vars optional merges for the email (FNAME, LNAME, etc.) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 bytes. Also, there are a few "special" keys:
1555	string EMAIL set this to change the email address. This is only respected on calls using update_existing or when passed to listUpdateMember()
1556	array GROUPINGS Set Interest Groups by Grouping. Each element in this array should be an array containing the "groups" parameter which contains a comma delimited list of Interest Groups to add. Commas in Interest Group names should be escaped with a backslash. ie, "," => "\," and either an "id" or "name" parameter to specify the Grouping - get from listInterestGroupings()
1557	string OPTINIP Set the Opt-in IP fields. <em>Abusing this may cause your account to be suspended.</em> We do validate this and it must not be a private IP address.
1558	array MC_LOCATION Set the members geographic location. By default if this merge field exists, we'll update using the optin_ip if it exists. If the array contains LATITUDE and LONGITUDE keys, they will be used. NOTE - this will slow down each subscribe call a bit, especially for lat/lng pairs in sparsely populated areas. Currently our automated background processes can and will overwrite this based on opens and clicks.
1559
1560	<strong>Handling Field Data Types</strong> - most fields you can just pass a string and all is well. For some, though, that is not the case...
1561	Field values should be formatted as follows:
1562	string address For the string version of an Address, the fields should be delimited by <strong>2</strong> spaces. Address 2 can be skipped. The Country should be a 2 character ISO-3166-1 code and will default to your default country if not set
1563	array address For the array version of an Address, the requirements for Address 2 and Country are the same as with the string version. Then simply pass us an array with the keys <strong>addr1</strong>, <strong>addr2</strong>, <strong>city</strong>, <strong>state</strong>, <strong>zip</strong>, <strong>country</strong> and appropriate values for each
1564
1565	string date use YYYY-MM-DD to be safe. Generally, though, anything strtotime() understands we'll understand - <a href="http://us2.php.net/strtotime" target="_blank">http://us2.php.net/strtotime</a>
1566	string dropdown can be a normal string - we <em>will</em> validate that the value is a valid option
1567	string image must be a valid, existing url. we <em>will</em> check its existence
1568	string multi_choice can be a normal string - we <em>will</em> validate that the value is a valid option
1569	double number pass in a valid number - anything else will turn in to zero (0). Note, this will be rounded to 2 decimal places
1570	string phone If your account has the US Phone numbers option set, this <em>must</em> be in the form of NPA-NXX-LINE (404-555-1212). If not, we assume an International number and will simply set the field with what ever number is passed in.
1571	string website This is a standard string, but we <em>will</em> verify that it looks like a valid URL
1572
1573	* @param string $email_type optional email type preference for the email (html, text, or mobile defaults to html)
1574	* @param bool $double_optin optional flag to control whether a double opt-in confirmation message is sent, defaults to true. <em>Abusing this may cause your account to be suspended.</em>
1575	* @param bool $update_existing optional flag to control whether a existing subscribers should be updated instead of throwing and error, defaults to false
1576	* @param bool $replace_interests optional flag to determine whether we replace the interest groups with the groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
1577	* @param bool $send_welcome optional if your double_optin is false and this is true, we will send your lists Welcome Email if this subscribe succeeds - this will not fire if we end up updating an existing subscriber. If double_optin is true, this has no effect. defaults to false.
1578	* @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)
1579	*/
1580	function listSubscribe($id, $email_address, $merge_vars=NULL, $email_type='html', $double_optin=true, $update_existing=false, $replace_interests=true, $send_welcome=false) {
1581	$params = array();
1582	$params["id"] = $id;
1583	$params["email_address"] = $email_address;
1584	$params["merge_vars"] = $merge_vars;
1585	$params["email_type"] = $email_type;
1586	$params["double_optin"] = $double_optin;
1587	$params["update_existing"] = $update_existing;
1588	$params["replace_interests"] = $replace_interests;
1589	$params["send_welcome"] = $send_welcome;
1590	return $this->callServer("listSubscribe", $params);
1591	}
1592
1593	/**
1594	* Unsubscribe the given email address from the list
1595	*
1596	* @section List Related
1597	* @example mcapi_listUnsubscribe.php
1598	* @example xml-rpc_listUnsubscribe.php
1599	*
1600	* @param string $id the list id to connect to. Get by calling lists()
1601	* @param string $email_address the email address to unsubscribe OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns
1602	* @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
1603	* @param boolean $send_goodbye flag to send the goodbye email to the email address, defaults to true
1604	* @param boolean $send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to true
1605	* @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)
1606	*/
1607	function listUnsubscribe($id, $email_address, $delete_member=false, $send_goodbye=true, $send_notify=true) {
1608	$params = array();
1609	$params["id"] = $id;
1610	$params["email_address"] = $email_address;
1611	$params["delete_member"] = $delete_member;
1612	$params["send_goodbye"] = $send_goodbye;
1613	$params["send_notify"] = $send_notify;
1614	return $this->callServer("listUnsubscribe", $params);
1615	}
1616
1617	/**
1618	* Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users,
1619	* consider using listBatchSubscribe() with the update_existing and possible replace_interests parameter.
1620	*
1621	* @section List Related
1622	* @example mcapi_listUpdateMember.php
1623	*
1624	* @param string $id the list id to connect to. Get by calling lists()
1625	* @param string $email_address the current email address of the member to update OR the "id" for the member returned from listMemberInfo, Webhooks, and Campaigns
1626	* @param array $merge_vars array of new field values to update the member with. See merge_vars in listSubscribe() for details.
1627	* @param string $email_type change the email type preference for the member ("html", "text", or "mobile"). Leave blank to keep the existing preference (optional)
1628	* @param boolean $replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
1629	* @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object
1630	*/
1631	function listUpdateMember($id, $email_address, $merge_vars, $email_type='', $replace_interests=true) {
1632	$params = array();
1633	$params["id"] = $id;
1634	$params["email_address"] = $email_address;
1635	$params["merge_vars"] = $merge_vars;
1636	$params["email_type"] = $email_type;
1637	$params["replace_interests"] = $replace_interests;
1638	return $this->callServer("listUpdateMember", $params);
1639	}
1640
1641	/**
1642	* Subscribe a batch of email addresses to a list at once. If you are using a serialized version of the API, we strongly suggest that you
1643	* only run this method as a POST request, and <em>not</em> a GET request. Maximum batch sizes vary based on the amount of data in each record,
1644	* though you should cap them at 5k - 10k records, depending on your experience. These calls are also long, so be sure you increase your timeout values.
1645	*
1646	* @section List Related
1647	*
1648	* @example mcapi_listBatchSubscribe.php
1649	* @example xml-rpc_listBatchSubscribe.php
1650	*
1651	* @param string $id the list id to connect to. Get by calling lists()
1652	* @param array $batch an array of structs for each address to import with two special keys: "EMAIL" for the email address, and "EMAIL_TYPE" for the email type option (html, text, or mobile)
1653	* @param boolean $double_optin flag to control whether to send an opt-in confirmation email - defaults to true
1654	* @param boolean $update_existing flag to control whether to update members that are already subscribed to the list or to return an error, defaults to false (return error)
1655	* @param boolean $replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
1656	* @return struct Array of result counts and any errors that occurred
1657	* @returnf int add_count Number of email addresses that were succesfully added
1658	* @returnf int update_count Number of email addresses that were succesfully updated
1659	* @returnf int error_count Number of email addresses that failed during addition/updating
1660	* @returnf array errors Array of error arrays, each containing:
1661	string code the error code
1662	string message the full error message
1663	string email the email address being processed
1664	*/
1665	function listBatchSubscribe($id, $batch, $double_optin=true, $update_existing=false, $replace_interests=true) {
1666	$params = array();
1667	$params["id"] = $id;
1668	$params["batch"] = $batch;
1669	$params["double_optin"] = $double_optin;
1670	$params["update_existing"] = $update_existing;
1671	$params["replace_interests"] = $replace_interests;
1672	return $this->callServer("listBatchSubscribe", $params);
1673	}
1674
1675	/**
1676	* Unsubscribe a batch of email addresses to a list
1677	*
1678	* @section List Related
1679	* @example mcapi_listBatchUnsubscribe.php
1680	*
1681	* @param string $id the list id to connect to. Get by calling lists()
1682	* @param array $emails array of email addresses to unsubscribe
1683	* @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
1684	* @param boolean $send_goodbye flag to send the goodbye email to the email addresses, defaults to true
1685	* @param boolean $send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to false
1686	* @return struct Array of result counts and any errors that occurred
1687	* @returnf int success_count Number of email addresses that were succesfully added/updated
1688	* @returnf int error_count Number of email addresses that failed during addition/updating
1689	* @returnf array errors Array of error structs. Each error struct will contain "code", "message", and "email"
1690	*/
1691	function listBatchUnsubscribe($id, $emails, $delete_member=false, $send_goodbye=true, $send_notify=false) {
1692	$params = array();
1693	$params["id"] = $id;
1694	$params["emails"] = $emails;
1695	$params["delete_member"] = $delete_member;
1696	$params["send_goodbye"] = $send_goodbye;
1697	$params["send_notify"] = $send_notify;
1698	return $this->callServer("listBatchUnsubscribe", $params);
1699	}
1700
1701	/**
1702	* Get all of the list members for a list that are of a particular status. Are you trying to get a dump including lots of merge
1703	* data or specific members of a list? If so, checkout the <a href="/api/export">Export API</a>
1704	*
1705	* @section List Related
1706	* @example mcapi_listMembers.php
1707	*
1708	* @param string $id the list id to connect to. Get by calling lists()
1709	* @param string $status the status to get members for - one of(subscribed, unsubscribed, <a target="_blank" href="http://eepurl.com/dwk1">cleaned</a>, updated), defaults to subscribed
1710	* @param string $since optional pull all members whose status (subscribed/unsubscribed/cleaned) has changed or whose profile (updated) has changed since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
1711	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1712	* @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 15000
1713	* @return array Array of a the total records match and matching list member data for this page (see Returned Fields for details)
1714	* @returnf int total the total matching records
1715	* @returnf array data the data for each member, including:
1716	string email Member email address
1717	date timestamp timestamp of their associated status date (subscribed, unsubscribed, cleaned, or updated) in GMT
1718	string reason For unsubscribes only - the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
1719	string reason_text For unsubscribes only - if the reason is OTHER, the text entered.
1720	*/
1721	function listMembers($id, $status='subscribed', $since=NULL, $start=0, $limit=100) {
1722	$params = array();
1723	$params["id"] = $id;
1724	$params["status"] = $status;
1725	$params["since"] = $since;
1726	$params["start"] = $start;
1727	$params["limit"] = $limit;
1728	return $this->callServer("listMembers", $params);
1729	}
1730
1731	/**
1732	* Get all the information for particular members of a list
1733	*
1734	* @section List Related
1735	* @example mcapi_listMemberInfo.php
1736	* @example xml-rpc_listMemberInfo.php
1737	*
1738	* @param string $id the list id to connect to. Get by calling lists()
1739	* @param array $email_address an array of up to 50 email addresses to get information for OR the "id"(s) for the member returned from listMembers, Webhooks, and Campaigns. For backwards compatibility, if a string is passed, it will be treated as an array with a single element (will not work with XML-RPC).
1740	* @return array array of list members with their info in an array (see Returned Fields for details)
1741	* @returnf int success the number of subscribers successfully found on the list
1742	* @returnf int errors the number of subscribers who were not found on the list
1743	* @returnf array data an array of arrays where each one has member info:
1744	string id The unique id for this email address on an account
1745	string email The email address associated with this record
1746	string email_type The type of emails this customer asked to get: html, text, or mobile
1747	array merges An associative array of all the merge tags and the data for those tags for this email address. <em>Note</em>: Interest Groups are returned as comma delimited strings - if a group name contains a comma, it will be escaped with a backslash. ie, "," => "\,". Groupings will be returned with their "id" and "name" as well as a "groups" field formatted just like Interest Groups
1748	string status The subscription status for this email address, either pending, subscribed, unsubscribed, or cleaned
1749	string ip_opt IP Address this address opted in from.
1750	string ip_signup IP Address this address signed up from.
1751	int member_rating the rating of the subscriber. This will be 1 - 5 as described <a href="http://eepurl.com/f-2P" target="_blank">here</a>
1752	string campaign_id If the user is unsubscribed and they unsubscribed from a specific campaign, that campaign_id will be listed, otherwise this is not returned.
1753	array lists An associative array of the other lists this member belongs to - the key is the list id and the value is their status in that list.
1754	date timestamp The time this email address was added to the list
1755	date info_changed The last time this record was changed. If the record is old enough, this may be blank.
1756	int web_id The Member id used in our web app, allows you to create a link directly to it
1757	array clients the various clients we've tracked the address as using - each included array includes client 'name' and 'icon_url'
1758	array static_segments the 'id', 'name', and date 'added' for any static segment this member is in
1759	*/
1760	function listMemberInfo($id, $email_address) {
1761	$params = array();
1762	$params["id"] = $id;
1763	$params["email_address"] = $email_address;
1764	return $this->callServer("listMemberInfo", $params);
1765	}
1766
1767	/**
1768	* Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to)
1769	*
1770	* @section List Related
1771	* @example mcapi_listMemberInfo.php
1772	* @example xml-rpc_listMemberInfo.php
1773	*
1774	* @param string $id the list id to connect to. Get by calling lists()
1775	* @param array $email_address an array of up to 50 email addresses to get information for OR the "id"(s) for the member returned from listMembers, Webhooks, and Campaigns.
1776	* @return array array of data and success/error counts
1777	* @returnf int success the number of subscribers successfully found on the list
1778	* @returnf int errors the number of subscribers who were not found on the list
1779	* @returnf array data an array of arrays where each activity record has:
1780	string action The action name, one of: open, click, bounce, unsub, abuse, sent
1781	string timestamp The date/time of the action
1782	string url For click actions, the url clicked, otherwise this is empty
1783	string bounce_type For bounce actions, the bounce type, otherwise this is empty
1784	string campaign_id The campaign id the action was related to, if it exists - otherwise empty (ie, direct unsub from list)
1785	*/
1786	function listMemberActivity($id, $email_address) {
1787	$params = array();
1788	$params["id"] = $id;
1789	$params["email_address"] = $email_address;
1790	return $this->callServer("listMemberActivity", $params);
1791	}
1792
1793	/**
1794	* Get all email addresses that complained about a given campaign
1795	*
1796	* @section List Related
1797	*
1798	* @example mcapi_listAbuseReports.php
1799	*
1800	* @param string $id the list id to pull abuse reports for (can be gathered using lists())
1801	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1802	* @param int $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
1803	* @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
1804	* @return array the total of all reports and the specific reports reports this page
1805	* @returnf int total the total number of matching abuse reports
1806	* @returnf array data the actual data for each reports, including:
1807	string date date/time the abuse report was received and processed
1808	string email the email address that reported abuse
1809	string campaign_id the unique id for the campaign that report was made against
1810	string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
1811	*/
1812	function listAbuseReports($id, $start=0, $limit=500, $since=NULL) {
1813	$params = array();
1814	$params["id"] = $id;
1815	$params["start"] = $start;
1816	$params["limit"] = $limit;
1817	$params["since"] = $since;
1818	return $this->callServer("listAbuseReports", $params);
1819	}
1820
1821	/**
1822	* Access the Growth History by Month for a given list.
1823	*
1824	* @section List Related
1825	*
1826	* @example mcapi_listGrowthHistory.php
1827	*
1828	* @param string $id the list id to connect to. Get by calling lists()
1829	* @return array array of months and growth
1830	* @returnf string month The Year and Month in question using YYYY-MM format
1831	* @returnf int existing number of existing subscribers to start the month
1832	* @returnf int imports number of subscribers imported during the month
1833	* @returnf int optins number of subscribers who opted-in during the month
1834	*/
1835	function listGrowthHistory($id) {
1836	$params = array();
1837	$params["id"] = $id;
1838	return $this->callServer("listGrowthHistory", $params);
1839	}
1840
1841	/**
1842	* Access up to the previous 180 days of daily detailed aggregated activity stats for a given list
1843	*
1844	* @section List Related
1845	*
1846	*
1847	* @param string $id the list id to connect to. Get by calling lists()
1848	* @return array array of array of daily values, each containing:
1849	* @returnf string day The day in YYYY-MM-DD
1850	* @returnf int emails_sent number of emails sent to the list
1851	* @returnf int unique_opens number of unique opens for the list
1852	* @returnf int recipient_clicks number of clicks for the list
1853	* @returnf int hard_bounce number of hard bounces for the list
1854	* @returnf int soft_bounce number of soft bounces for the list
1855	* @returnf int abuse_reports number of abuse reports for the list
1856	* @returnf int subs number of double optin subscribes for the list
1857	* @returnf int unsubs number of manual unsubscribes for the list
1858	* @returnf int other_adds number of non-double optin subscribes for the list (manual, API, or import)
1859	* @returnf int other_removes number of non-manual unsubscribes for the list (deletions, empties, soft-bounce removals)
1860	*/
1861	function listActivity($id) {
1862	$params = array();
1863	$params["id"] = $id;
1864	return $this->callServer("listActivity", $params);
1865	}
1866
1867	/**
1868	* Retrieve the locations (countries) that the list's subscribers have been tagged to based on geocoding their IP address
1869	*
1870	* @section List Related
1871	*
1872	* @param string $id the list id to connect to. Get by calling lists()
1873	* @return array array of locations
1874	* @returnf string country the country name
1875	* @returnf string cc the 2 digit country code
1876	* @returnf double percent the percent of subscribers in the country
1877	* @returnf double total the total number of subscribers in the country
1878	*/
1879	function listLocations($id) {
1880	$params = array();
1881	$params["id"] = $id;
1882	return $this->callServer("listLocations", $params);
1883	}
1884
1885	/**
1886	* Retrieve the clients that the list's subscribers have been tagged as being used based on user agents seen. Made possible by <a href="http://user-agent-string.info" target="_blank">user-agent-string.info</a>
1887	*
1888	* @section List Related
1889	*
1890	* @param string $id the list id to connect to. Get by calling lists()
1891	* @return array the desktop and mobile user agents in use on the list
1892	* @returnf array desktop desktop user agents and percentages
1893	double penetration the percent of desktop clients in use
1894	array clients a record containing the 'client', an 'icon' image url, the 'percent' using the client, and the total 'members' represented
1895	* @returnf array mobile mobile user agents and percentages
1896	double penetration the percent of mobile clients in use
1897	array clients a record containing the 'client', an 'icon' image url, the 'percent' using the client, and the total 'members' represented
1898	*/
1899	function listClients($id) {
1900	$params = array();
1901	$params["id"] = $id;
1902	return $this->callServer("listClients", $params);
1903	}
1904
1905	/**
1906	* Retrieve various templates available in the system, allowing some thing similar to our template gallery to be created.
1907	*
1908	* @section Template Related
1909	* @example mcapi_templates.php
1910	* @example xml-rpc_templates.php
1911	*
1912	* @param array $types optional the types of templates to return
1913	boolean user Customer template for this user account. Defaults to true.
1914	boolean gallery Templates from our Gallery. Note that some templates that require extra configuration are withheld. (eg, the Etsy template). Defaults to false.
1915	boolean base Our "start from scratch" extremely basic templates
1916	* @param string $category optional for Gallery templates only, limit to a specific template category
1917	* @param array $inactives optional options to control how inactive templates are returned, if at all
1918	boolean include user templates are not deleted, only set inactive. defaults to false.
1919	boolean only only include inactive templates. defaults to false.
1920	* @return array An array of structs, one for each template (see Returned Fields for details)
1921	* @returnf int id Id of the template
1922	* @returnf string name Name of the template
1923	* @returnf string layout Layout of the template - "basic", "left_column", "right_column", or "postcard"
1924	* @returnf string preview_image If we've generated it, the url of the preview image for the template. We do out best to keep these up to date, but Preview image urls are not guaranteed to be available
1925	* @returnf string date_created The date/time the template was created
1926	* @returnf bool edit_source Whether or not you are able to edit the source of a template.
1927	*/
1928	function templates($types=array (
1929	), $category=NULL, $inactives=array (
1930	)) {
1931	$params = array();
1932	$params["types"] = $types;
1933	$params["category"] = $category;
1934	$params["inactives"] = $inactives;
1935	return $this->callServer("templates", $params);
1936	}
1937
1938	/**
1939	* Pull details for a specific template to help support editing
1940	*
1941	* @section Template Related
1942	*
1943	* @param int $tid the template id - get from templates()
1944	* @param string $type the template type to load - one of 'user', 'gallery', 'base'
1945	* @return array an array of info to be used when editing
1946	* @returnf array default_content the default content broken down into the named editable sections for the template
1947	* @returnf array sections the valid editable section names
1948	* @returnf string source the full source of the template as if you exported it via our template editor
1949	* @returnf string preview similar to the source, but the rendered version of the source from our popup preview
1950	*/
1951	function templateInfo($tid, $type='user') {
1952	$params = array();
1953	$params["tid"] = $tid;
1954	$params["type"] = $type;
1955	return $this->callServer("templateInfo", $params);
1956	}
1957
1958	/**
1959	* Create a new user template, <strong>NOT</strong> campaign content. These templates can then be applied while creating campaigns.
1960	*
1961	* @section Template Related
1962	* @example mcapi_create_template.php
1963	* @example xml-rpc_create_template.php
1964	*
1965	* @param string $name the name for the template - names must be unique and a max of 50 bytes
1966	* @param string $html a string specifying the entire template to be created. This is <strong>NOT</strong> campaign content. They are intended to utilize our <a href="http://www.mailchimp.com/resources/email-template-language/" target="_blank">template language</a>.
1967	* @return int the new template id, otherwise an error is thrown.
1968	*/
1969	function templateAdd($name, $html) {
1970	$params = array();
1971	$params["name"] = $name;
1972	$params["html"] = $html;
1973	return $this->callServer("templateAdd", $params);
1974	}
1975
1976	/**
1977	* Replace the content of a user template, <strong>NOT</strong> campaign content.
1978	*
1979	* @section Template Related
1980	*
1981	* @param int $id the id of the user template to update
1982	* @param array $values the values to updates - while both are optional, at least one should be provided. Both can be updated at the same time.
1983	string name optional the name for the template - names must be unique and a max of 50 bytes
1984	string html optional a string specifying the entire template to be created. This is <strong>NOT</strong> campaign content. They are intended to utilize our <a href="http://www.mailchimp.com/resources/email-template-language/" target="_blank">template language</a>.
1985
1986	* @return boolean true if the template was updated, otherwise an error will be thrown
1987	*/
1988	function templateUpdate($id, $values) {
1989	$params = array();
1990	$params["id"] = $id;
1991	$params["values"] = $values;
1992	return $this->callServer("templateUpdate", $params);
1993	}
1994
1995	/**
1996	* Delete (deactivate) a user template
1997	*
1998	* @section Template Related
1999	*
2000	* @param int $id the id of the user template to delete
2001	* @return boolean true if the template was deleted, otherwise an error will be thrown
2002	*/
2003	function templateDel($id) {
2004	$params = array();
2005	$params["id"] = $id;
2006	return $this->callServer("templateDel", $params);
2007	}
2008
2009	/**
2010	* Undelete (reactivate) a user template
2011	*
2012	* @section Template Related
2013	*
2014	* @param int $id the id of the user template to reactivate
2015	* @return boolean true if the template was deleted, otherwise an error will be thrown
2016	*/
2017	function templateUndel($id) {
2018	$params = array();
2019	$params["id"] = $id;
2020	return $this->callServer("templateUndel", $params);
2021	}
2022
2023	/**
2024	* Retrieve lots of account information including payments made, plan info, some account stats, installed modules,
2025	* contact info, and more. No private information like Credit Card numbers is available.
2026	*
2027	* @section Helper
2028	*
2029	* @return array containing the details for the account tied to this API Key
2030	* @returnf string username The Account username
2031	* @returnf string user_id The Account user unique id (for building some links)
2032	* @returnf bool is_trial Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
2033	* @returnf string timezone The timezone for the Account - default is "US/Eastern"
2034	* @returnf string plan_type Plan Type - "monthly", "payasyougo", or "free"
2035	* @returnf int plan_low <em>only for Monthly plans</em> - the lower tier for list size
2036	* @returnf int plan_high <em>only for Monthly plans</em> - the upper tier for list size
2037	* @returnf string plan_start_date <em>only for Monthly plans</em> - the start date for a monthly plan
2038	* @returnf int emails_left <em>only for Free and Pay-as-you-go plans</em> emails credits left for the account
2039	* @returnf bool pending_monthly Whether the account is finishing Pay As You Go credits before switching to a Monthly plan
2040	* @returnf string first_payment date of first payment
2041	* @returnf string last_payment date of most recent payment
2042	* @returnf int times_logged_in total number of times the account has been logged into via the web
2043	* @returnf string last_login date/time of last login via the web
2044	* @returnf string affiliate_link Monkey Rewards link for our Affiliate program
2045	* @returnf array contact Contact details for the account
2046	string fname First Name
2047	string lname Last Name
2048	string email Email Address
2049	string company Company Name
2050	string address1 Address Line 1
2051	string address2 Address Line 2
2052	string city City
2053	string state State or Province
2054	string zip Zip or Postal Code
2055	string country Country name
2056	string url Website URL
2057	string phone Phone number
2058	string fax Fax number
2059	* @returnf array modules Addons installed in the account
2060	string name The module name
2061	string added The date the module was added
2062	* @returnf array orders Order details for the account
2063	int order_id The order id
2064	string type The order type - either "monthly" or "credits"
2065	double amount The order amount
2066	string date The order date
2067	double credits_used The total credits used
2068	* @returnf array rewards Rewards details for the account including credits & inspections earned, number of referals, referal details, and rewards used
2069	int referrals_this_month the total number of referrals this month
2070	string notify_on whether or not we notify the user when rewards are earned
2071	string notify_email the email address address used for rewards notifications
2072	array credits Email credits earned "this_month", "total_earned", and "remaining"
2073	array inspections Inbox Inspections earned "this_month", "total_earned", and "remaining"
2074	array referrals All referrals, including "name", "email", "signup_date", and "type"
2075	array applied Applied rewards, including "value", "date", "order_id", and "order_desc"
2076	*/
2077	function getAccountDetails() {
2078	$params = array();
2079	return $this->callServer("getAccountDetails", $params);
2080	}
2081
2082	/**
2083	* Have HTML content auto-converted to a text-only format. You can send: plain HTML, an array of Template content, an existing Campaign Id, or an existing Template Id. Note that this will <b>not</b> save anything to or update any of your lists, campaigns, or templates.
2084	*
2085	* @section Helper
2086	* @example xml-rpc_generateText.php
2087	*
2088	* @param string $type The type of content to parse. Must be one of: "html", "template", "url", "cid" (Campaign Id), or "tid" (Template Id)
2089	* @param mixed $content The content to use. For "html" expects a single string value, "template" expects an array like you send to campaignCreate, "url" expects a valid & public URL to pull from, "cid" expects a valid Campaign Id, and "tid" expects a valid Template Id on your account.
2090	* @return string the content pass in converted to text.
2091	*/
2092	function generateText($type, $content) {
2093	$params = array();
2094	$params["type"] = $type;
2095	$params["content"] = $content;
2096	return $this->callServer("generateText", $params);
2097	}
2098
2099	/**
2100	* Send your HTML content to have the CSS inlined and optionally remove the original styles.
2101	*
2102	* @section Helper
2103	* @example xml-rpc_inlineCss.php
2104	*
2105	* @param string $html Your HTML content
2106	* @param bool $strip_css optional Whether you want the CSS <style> tags stripped from the returned document. Defaults to false.
2107	* @return string Your HTML content with all CSS inlined, just like if we sent it.
2108	*/
2109	function inlineCss($html, $strip_css=false) {
2110	$params = array();
2111	$params["html"] = $html;
2112	$params["strip_css"] = $strip_css;
2113	return $this->callServer("inlineCss", $params);
2114	}
2115
2116	/**
2117	* List all the folders for a user account
2118	*
2119	* @section Folder Related
2120	* @example mcapi_folders.php
2121	* @example xml-rpc_folders.php
2122	*
2123	* @param string $type optional the type of folders to return - either "campaign" or "autoresponder". Defaults to "campaign"
2124	* @return array Array of folder structs (see Returned Fields for details)
2125	* @returnf int folder_id Folder Id for the given folder, this can be used in the campaigns() function to filter on.
2126	* @returnf string name Name of the given folder
2127	* @returnf string date_created The date/time the folder was created
2128	* @returnf string type The type of the folders being returned, just to make sure you know.
2129	*/
2130	function folders($type='campaign') {
2131	$params = array();
2132	$params["type"] = $type;
2133	return $this->callServer("folders", $params);
2134	}
2135
2136	/**
2137	* Add a new folder to file campaigns or autoresponders in
2138	*
2139	* @section Folder Related
2140	* @example mcapi_folderAdd.php
2141	* @example xml-rpc_folderAdd.php
2142	*
2143	* @param string $name a unique name for a folder (max 100 bytes)
2144	* @param string $type optional the type of folder to create - either "campaign" or "autoresponder". Defaults to "campaign"
2145	* @return int the folder_id of the newly created folder.
2146	*/
2147	function folderAdd($name, $type='campaign') {
2148	$params = array();
2149	$params["name"] = $name;
2150	$params["type"] = $type;
2151	return $this->callServer("folderAdd", $params);
2152	}
2153
2154	/**
2155	* Update the name of a folder for campaigns or autoresponders
2156	*
2157	* @section Folder Related
2158	*
2159	* @param int $fid the folder id to update - retrieve from folders()
2160	* @param string $name a new, unique name for the folder (max 100 bytes)
2161	* @param string $type optional the type of folder to create - either "campaign" or "autoresponder". Defaults to "campaign"
2162	* @return bool true if the update worked, otherwise an exception is thrown
2163	*/
2164	function folderUpdate($fid, $name, $type='campaign') {
2165	$params = array();
2166	$params["fid"] = $fid;
2167	$params["name"] = $name;
2168	$params["type"] = $type;
2169	return $this->callServer("folderUpdate", $params);
2170	}
2171
2172	/**
2173	* Delete a campaign or autoresponder folder. Note that this will simply make campaigns in the folder appear unfiled, they are not removed.
2174	*
2175	* @section Folder Related
2176	*
2177	* @param int $fid the folder id to update - retrieve from folders()
2178	* @param string $type optional the type of folder to create - either "campaign" or "autoresponder". Defaults to "campaign"
2179	* @return bool true if the delete worked, otherwise an exception is thrown
2180	*/
2181	function folderDel($fid, $type='campaign') {
2182	$params = array();
2183	$params["fid"] = $fid;
2184	$params["type"] = $type;
2185	return $this->callServer("folderDel", $params);
2186	}
2187
2188	/**
2189	* Retrieve the Ecommerce Orders for an account
2190	*
2191	* @section Ecommerce
2192	*
2193	* @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
2194	* @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
2195	* @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
2196	* @return array the total matching orders and the specific orders for the requested page
2197	* @returnf int total the total matching orders
2198	* @returnf array data the actual data for each order being returned
2199	string store_id the store id generated by the plugin used to uniquely identify a store
2200	string store_name the store name collected by the plugin - often the domain name
2201	string order_id the internal order id the store tracked this order by
2202	string email the email address that received this campaign and is associated with this order
2203	double order_total the order total
2204	double tax_total the total tax for the order (if collected)
2205	double ship_total the shipping total for the order (if collected)
2206	string order_date the date the order was tracked - from the store if possible, otherwise the GMT time we recieved it
2207	array lines containing detail of the order - product, category, quantity, item cost
2208	*/
2209	function ecommOrders($start=0, $limit=100, $since=NULL) {
2210	$params = array();
2211	$params["start"] = $start;
2212	$params["limit"] = $limit;
2213	$params["since"] = $since;
2214	return $this->callServer("ecommOrders", $params);
2215	}
2216
2217	/**
2218	* Import Ecommerce Order Information to be used for Segmentation. This will generally be used by ecommerce package plugins
2219	* <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
2220	* @section Ecommerce
2221	*
2222	* @param array $order an array of information pertaining to the order that has completed. Use the following keys:
2223	string id the Order Id
2224	string email_id optional (kind of) the Email Id of the subscriber we should attach this order to (see the "mc_eid" query string variable a campaign passes) - either this or <strong>email</strong> is required. If both are provided, email_id takes precedence
2225	string email optional (kind of) the Email Address we should attach this order to - either this or <strong>email_id</strong> is required. If both are provided, email_id takes precedence
2226	double total The Order Total (ie, the full amount the customer ends up paying)
2227	string order_date optional the date of the order - if this is not provided, we will default the date to now
2228	double shipping optional the total paid for Shipping Fees
2229	double tax optional the total tax paid
2230	string store_id a unique id for the store sending the order in (20 bytes max)
2231	string store_name optional a "nice" name for the store - typically the base web address (ie, "store.mailchimp.com"). We will automatically update this if it changes (based on store_id)
2232	string plugin_id the MailChimp assigned Plugin Id. Get yours by <a href="/api/register.php">registering here</a>
2233	string campaign_id optional the Campaign Id to track this order with (see the "mc_cid" query string variable a campaign passes)
2234	array items the individual line items for an order using these keys:
2235	<div style="padding-left:30px"><table><tr><td colspan=*>
2236	int line_num optional the line number of the item on the order. We will generate these if they are not passed
2237	int product_id the store's internal Id for the product. Lines that do no contain this will be skipped
2238	string product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
2239	int category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
2240	string category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
2241	double qty the quantity of the item ordered
2242	double cost the cost of a single item (ie, not the extended cost of the line)
2243	</td></tr></table></div>
2244	* @return bool true if the data is saved, otherwise an error is thrown.
2245	*/
2246	function ecommOrderAdd($order) {
2247	$params = array();
2248	$params["order"] = $order;
2249	return $this->callServer("ecommOrderAdd", $params);
2250	}
2251
2252	/**
2253	* Delete Ecommerce Order Information used for segmentation. This will generally be used by ecommerce package plugins
2254	* <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
2255	* @section Ecommerce
2256	*
2257	* @param string $store_id the store id the order belongs to
2258	* @param string $order_id the order id (generated by the store) to delete
2259	* @return bool true if an order is deleted, otherwise an error is thrown.
2260	*/
2261	function ecommOrderDel($store_id, $order_id) {
2262	$params = array();
2263	$params["store_id"] = $store_id;
2264	$params["order_id"] = $order_id;
2265	return $this->callServer("ecommOrderDel", $params);
2266	}
2267
2268	/**
2269	* Retrieve all List Ids a member is subscribed to.
2270	*
2271	* @section Helper
2272	*
2273	* @param string $email_address the email address to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns
2274	* @return array An array of list_ids the member is subscribed to.
2275	*/
2276	function listsForEmail($email_address) {
2277	$params = array();
2278	$params["email_address"] = $email_address;
2279	return $this->callServer("listsForEmail", $params);
2280	}
2281
2282	/**
2283	* Retrieve all Campaigns Ids a member was sent
2284	*
2285	* @section Helper
2286	*
2287	* @param string $email_address the email address to unsubscribe OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns
2288	* @return array An array of campaign_ids the member received
2289	*/
2290	function campaignsForEmail($email_address) {
2291	$params = array();
2292	$params["email_address"] = $email_address;
2293	return $this->callServer("campaignsForEmail", $params);
2294	}
2295
2296	/**
2297	* Return the current Chimp Chatter messages for an account.
2298	*
2299	* @section Helper
2300	*
2301	* @return array An array of chatter messages and properties
2302	* @returnf string message The chatter message
2303	* @returnf string type The type of the message - one of lists:new-subscriber, lists:unsubscribes, lists:profile-updates, campaigns:facebook-likes, campaigns:facebook-comments, campaigns:forward-to-friend, lists:imports, or campaigns:inbox-inspections
2304	* @returnf string url a url into the web app that the message could link to
2305	* @returnf string list_id the list_id a message relates to, if applicable
2306	* @returnf string campaign_id the list_id a message relates to, if applicable
2307	* @returnf string update_time The date/time the message was last updated
2308	*/
2309	function chimpChatter() {
2310	$params = array();
2311	return $this->callServer("chimpChatter", $params);
2312	}
2313
2314	/**
2315	* Retrieve a list of all MailChimp API Keys for this User
2316	*
2317	* @section Security Related
2318	* @example xml-rpc_apikeyAdd.php
2319	* @example mcapi_apikeyAdd.php
2320	*
2321	* @param string $username Your MailChimp user name
2322	* @param string $password Your MailChimp password
2323	* @param boolean $expired optional - whether or not to include expired keys, defaults to false
2324	* @return array an array of API keys including:
2325	* @returnf string apikey The api key that can be used
2326	* @returnf string created_at The date the key was created
2327	* @returnf string expired_at The date the key was expired
2328	*/
2329	function apikeys($username, $password, $expired=false) {
2330	$params = array();
2331	$params["username"] = $username;
2332	$params["password"] = $password;
2333	$params["expired"] = $expired;
2334	return $this->callServer("apikeys", $params);
2335	}
2336
2337	/**
2338	* Add an API Key to your account. We will generate a new key for you and return it.
2339	*
2340	* @section Security Related
2341	* @example xml-rpc_apikeyAdd.php
2342	*
2343	* @param string $username Your MailChimp user name
2344	* @param string $password Your MailChimp password
2345	* @return string a new API Key that can be immediately used.
2346	*/
2347	function apikeyAdd($username, $password) {
2348	$params = array();
2349	$params["username"] = $username;
2350	$params["password"] = $password;
2351	return $this->callServer("apikeyAdd", $params);
2352	}
2353
2354	/**
2355	* Expire a Specific API Key. Note that if you expire all of your keys, just visit <a href="http://admin.mailchimp.com/account/api" target="_blank">your API dashboard</a>
2356	* to create a new one. If you are trying to shut off access to your account for an old developer, change your
2357	* MailChimp password, then expire all of the keys they had access to. Note that this takes effect immediately, so make
2358	* sure you replace the keys in any working application before expiring them! Consider yourself warned...
2359	*
2360	* @section Security Related
2361	* @example mcapi_apikeyExpire.php
2362	* @example xml-rpc_apikeyExpire.php
2363	*
2364	* @param string $username Your MailChimp user name
2365	* @param string $password Your MailChimp password
2366	* @return boolean true if it worked, otherwise an error is thrown.
2367	*/
2368	function apikeyExpire($username, $password) {
2369	$params = array();
2370	$params["username"] = $username;
2371	$params["password"] = $password;
2372	return $this->callServer("apikeyExpire", $params);
2373	}
2374
2375	/**
2376	* "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good. Note
2377	* than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different
2378	* string back that will explain our view on what is going on.
2379	*
2380	* @section Helper
2381	* @example xml-rpc_ping.php
2382	*
2383	* @return string returns "Everything's Chimpy!" if everything is chimpy, otherwise returns an error message
2384	*/
2385	function ping() {
2386	$params = array();
2387	return $this->callServer("ping", $params);
2388	}
2389
2390	/**
2391	* Internal function - proxy method for certain XML-RPC calls \| DO NOT CALL
2392	* @param mixed Method to call, with any parameters to pass along
2393	* @return mixed the result of the call
2394	*/
2395	function callMethod() {
2396	$params = array();
2397	return $this->callServer("callMethod", $params);
2398	}
2399
2400	/**
2401	* Actually connect to the server and call the requested methods, parsing the result
2402	* You should never have to call this function manually
2403	*/
2404	function callServer($method, $params) {
2405	$dc = "us1";
2406	if (strstr($this->api_key,"-")){
2407	list($key, $dc) = explode("-",$this->api_key,2);
2408	if (!$dc) $dc = "us1";
2409	}
2410	$this->apiUrl["prefix"] = $dc;
2411	$host = $dc.".".$this->apiUrl["host"];
2412	$params["apikey"] = $this->api_key;
2413
2414	$this->errorMessage = "";
2415	$this->errorCode = "";
2416	$sep_changed = false;
2417	//sigh, apparently some distribs change this to & by default
2418	if (ini_get("arg_separator.output")!="&"){
2419	$sep_changed = true;
2420	$orig_sep = ini_get("arg_separator.output");
2421	ini_set("arg_separator.output", "&");
2422	}
2423	$post_vars = http_build_query($params);
2424	if ($sep_changed){
2425	ini_set("arg_separator.output", $orig_sep);
2426	}
2427
2428	# $payload = "POST " . $this->apiUrl["path"] . "?" . $this->apiUrl["query"] . "&method=" . $method . " HTTP/1.0\r\n";
2429	# $payload .= "Host: " . $host . "\r\n";
2430	# $payload .= "User-Agent: MCAPI/" . $this->version ."\r\n";
2431	# $payload .= "Content-type: application/x-www-form-urlencoded\r\n";
2432	# $payload .= "Content-length: " . strlen($post_vars) . "\r\n";
2433	# $payload .= "Connection: close \r\n\r\n";
2434	# $payload .= $post_vars;
2435
2436	ob_start();
2437
2438	$s2_ags = array("user-agent" => "MCAPI/" . $this->version, "timeout" => $this->timeout);
2439
2440	$s2_url = $host . $this->apiUrl["path"] . "?" . $this->apiUrl["query"] . "&method=" . $method;
2441	$s2_url = ($this->secure) ? "https://" . $s2_url : "http://" . $s2_url;
2442
2443	if (!strlen ($response = c_ws_plugin__s2member_utils_urls::remote ($s2_url, $post_vars, $s2_ags, true))){
2444	$this->errorMessage = "Could not connect.";
2445	$this->errorCode = "-99";
2446	ob_end_clean();
2447	return false;
2448	}
2449
2450	ob_end_clean();
2451
2452	# if ($this->secure){
2453	# $sock = fsockopen("ssl://".$host, 443, $errno, $errstr, 30);
2454	# } else {
2455	# $sock = fsockopen($host, 80, $errno, $errstr, 30);
2456	# }
2457	# if(!$sock) {
2458	# $this->errorMessage = "Could not connect (ERR $errno: $errstr)";
2459	# $this->errorCode = "-99";
2460	# ob_end_clean();
2461	# return false;
2462	# }
2463
2464	# $response = "";
2465	# fwrite($sock, $payload);
2466	# stream_set_timeout($sock, $this->timeout);
2467	# $info = stream_get_meta_data($sock);
2468	# while ((!feof($sock)) && (!$info["timed_out"])) {
2469	# $response .= fread($sock, $this->chunkSize);
2470	# $info = stream_get_meta_data($sock);
2471	# }
2472	# fclose($sock);
2473	# ob_end_clean();
2474	# if ($info["timed_out"]) {
2475	# $this->errorMessage = "Could not read response (timed out)";
2476	# $this->errorCode = -98;
2477	# return false;
2478	# }
2479
2480	list($headers, $response) = explode("\r\n\r\n", $response, 2);
2481	$headers = explode("\r\n", $headers);
2482	$errored = false;
2483	foreach($headers as $h){
2484	if (substr( /* WebSharks, Inc. ( lowercase ). */
2485	strtolower($h),0,26)==="x-mailchimp-api-error-code"){
2486	$errored = true;
2487	$error_code = trim(substr($h,27));
2488	break;
2489	}
2490	}
2491
2492	# if(ini_get("magic_quotes_runtime")) $response = stripslashes($response);
2493
2494	$serial = /* WebSharks, Inc. ( maybe ). */ maybe_unserialize($response);
2495
2496	if($response && $serial === false) {
2497	$response = array("error" => "Bad Response. Got This: " . $response, "code" => "-99");
2498	} else {
2499	$response = $serial;
2500	}
2501	if($errored && is_array($response) && isset($response["error"])) {
2502	$this->errorMessage = $response["error"];
2503	$this->errorCode = $response["code"];
2504	return false;
2505	} elseif($errored){
2506	$this->errorMessage = "No error message was found.";
2507	$this->errorCode = $error_code;
2508	return false;
2509	}
2510
2511	return $response;
2512	}
2513
2514	}
2515
2516	?>