MailChimp List Subscribe Form - Version 1.1

Version Description

Download this release

Release Info

Developer mc_jesse
Plugin Icon wp plugin MailChimp List Subscribe Form
Version 1.1
Comparing to
See all releases

Code changes from version 0.1 to 1.1

MCAPI.class.php CHANGED
@@ -1,7 +1,7 @@
1
  <?php
2
 
3
  class MCAPI {
4
- var $version = "1.0";
5
  var $errorMessage;
6
  var $errorCode;
7
 
@@ -21,28 +21,59 @@ class MCAPI {
21
  var $chunkSize = 8192;
22
 
23
  /**
24
- * Cache the user id so we only have to log in once per client instantiation
25
  */
26
- var $uuid;
 
 
 
 
 
27
 
28
  /**
29
  * Connect to the MailChimp API for a given list. All MCAPI calls require login before functioning
30
  *
31
- * @param string $username Your MailChimp login user name - always required
32
- * @param string $password Your MailChimp login password - always required
33
  */
34
- function MCAPI($username, $password) {
 
 
35
  $this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
36
- $this->uuid = $this->callServer("login", array("username" => $username, "password" => $password));
 
 
 
 
 
 
 
37
  }
38
-
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
39
  /**
40
  * Unschedule a campaign that is scheduled to be sent in the future
41
  *
42
  * @section Campaign Related
 
43
  * @example xml-rpc_campaignUnschedule.php
44
  *
45
- * @param string $cid the id for the campaign to unschedule
46
  * @return boolean true on success
47
  */
48
  function campaignUnschedule($cid) {
@@ -55,26 +86,59 @@ class MCAPI {
55
  * Schedule a campaign to be sent in the future
56
  *
57
  * @section Campaign Related
 
58
  * @example xml-rpc_campaignSchedule.php
59
  *
60
- * @param string $cid the id for the campaign to schedule
61
- * @param string $schedule_time the time to schedule the campaign - in YYYY-MM-DD HH:II:SS format in GMT
 
62
  * @return boolean true on success
63
  */
64
- function campaignSchedule($cid, $schedule_time) {
65
  $params = array();
66
  $params["cid"] = $cid;
67
  $params["schedule_time"] = $schedule_time;
 
68
  return $this->callServer("campaignSchedule", $params);
69
  }
70
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
71
  /**
72
  * Send a given campaign immediately
73
  *
74
  * @section Campaign Related
75
- * @example xml-rpc_campaignSend.php
76
  *
77
- * @param string $cid the id for the campaign to send
 
 
 
78
  * @return boolean true on success
79
  */
80
  function campaignSendNow($cid) {
@@ -87,11 +151,13 @@ class MCAPI {
87
  * Send a test of this campaign to the provided email address
88
  *
89
  * @section Campaign Related
 
 
90
  * @example xml-rpc_campaignSendTest.php
91
  *
92
- * @param string $cid the id for the campaign to test
93
- * @param string $test_emails an array of email address to receive the test message
94
- * @param string $send_type optional default (null) sends both, "html" or "text" send just that format
95
  * @return boolean true on success
96
  */
97
  function campaignSendTest($cid, $test_emails=array (
@@ -107,6 +173,7 @@ class MCAPI {
107
  * Retrieve all templates defined for your user account
108
  *
109
  * @section Campaign Related
 
110
  * @example xml-rpc_campaignTemplates.php
111
  *
112
  * @return array An array of structs, one for each template (see Returned Fields for details)
@@ -120,83 +187,221 @@ class MCAPI {
120
  return $this->callServer("campaignTemplates", $params);
121
  }
122
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
123
  /**
124
  * Create a new draft campaign to send
125
  *
126
  * @section Campaign Related
127
- * @example xml-rpc_createCampaign.php
128
- *
129
- * @param string $list_id the list to send this campaign to- get lists using getLists()
130
- * @param string $subject the subject line for your campaign message
131
- * @param string $from_email the From: email address for your campaign message
132
- * @param string $from_name the From: name for your campaign message
133
- * @param array $content the content for this campaign - use a struct with the following keys: "html" for pasted HTML content and "text" for the plain-text version. 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.
134
- * @param integer $template_id optional - use this template to generate the HTML content of the campaign
135
- * @param 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.
136
- * @param string $title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
137
- * @param boolean $authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false
138
- * @param string $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
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
139
  * @return string the ID for the created campaign
140
  */
141
- function campaignCreate($list_id, $subject, $from_email, $from_name, $content, $template_id=NULL, $tracking=array (
142
- 'opens' => true,
143
- 'html_clicks' => true,
144
- 'text_clicks' => false,
145
- ), $title=NULL, $authenticate=false, $analytics=NULL) {
146
  $params = array();
147
- $params["list_id"] = $list_id;
148
- $params["subject"] = $subject;
149
- $params["from_email"] = $from_email;
150
- $params["from_name"] = $from_name;
151
  $params["content"] = $content;
152
- $params["template_id"] = $template_id;
153
- $params["tracking"] = $tracking;
154
- $params["title"] = $title;
155
- $params["authenticate"] = $authenticate;
156
- $params["analytics"] = $analytics;
157
  return $this->callServer("campaignCreate", $params);
158
  }
159
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
160
  /**
161
- * Get the list of campaigns and associated information for a list
162
  *
163
  * @section Campaign Related
 
 
164
  *
165
- * @param string $filter_id optional - only show campaigns from this list id - get lists using getLists()
166
- * @param integer $filter_folder optional - only show campaigns from this folder id - get folders using campaignFolders()
167
- * @param string $filter_fromname optional - only show campaigns that have this "From Name"
168
- * @param string $filter_fromemail optional - only show campaigns that have this "Reply-to Email"
169
- * @param string $filter_title optional - only show campaigns that have this title
170
- * @param string $filter_subject optional - only show campaigns that have this subject
171
- * @param string $filter_sendtimestart optional - only show campaigns that have been sent since this date/time
172
- * @param string $filter_sendtimeend optional - only show campaigns that have been sent before this date/time
173
- * @param boolean $filter_exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values
174
- * @param integer $start optional - control paging of campaigns, start results at this campaign #, defaults to 0 (beginning)
175
- * @param integer $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=5000)
 
 
 
176
  * @return array list of campaigns and their associated information (see Returned Fields for description)
177
  * @returnf string id Campaign Id (used for all other campaign functions)
 
178
  * @returnf string title Title of the campaign
 
179
  * @returnf date create_time Creation time for the campaign
180
  * @returnf date send_time Send time for the campaign
181
- * @returnf int emails_sent Number of emails email was sent to
182
- * @returnf string status Status of the given campaign (sent,scheduled,etc.)
183
  * @returnf string from_name From name of the given campaign
184
  * @returnf string from_email Reply-to email of the given campaign
185
  * @returnf string subject Subject of the given campaign
186
- * @returnf string to_email To email string
187
  * @returnf string archive_url Archive link for the given campaign
 
 
 
 
 
 
188
  */
189
- function campaigns($filter_id=NULL, $filter_folder=NULL, $filter_fromname=NULL, $filter_fromemail=NULL, $filter_title=NULL, $filter_subject=NULL, $filter_sendtimestart=NULL, $filter_sendtimeend=NULL, $filter_exact=true, $start=0, $limit=25) {
190
- $params = array();
191
- $params["filter_id"] = $filter_id;
192
- $params["filter_folder"] = $filter_folder;
193
- $params["filter_fromname"] = $filter_fromname;
194
- $params["filter_fromemail"] = $filter_fromemail;
195
- $params["filter_title"] = $filter_title;
196
- $params["filter_subject"] = $filter_subject;
197
- $params["filter_sendtimestart"] = $filter_sendtimestart;
198
- $params["filter_sendtimeend"] = $filter_sendtimeend;
199
- $params["filter_exact"] = $filter_exact;
200
  $params["start"] = $start;
201
  $params["limit"] = $limit;
202
  return $this->callServer("campaigns", $params);
@@ -206,6 +411,8 @@ class MCAPI {
206
  * List all the folders for a user account
207
  *
208
  * @section Campaign Related
 
 
209
  *
210
  * @return array Array of folder structs (see Returned Fields for details)
211
  * @returnf integer folder_id Folder Id for the given folder, this can be used in the campaigns() function to filter on.
@@ -221,7 +428,10 @@ class MCAPI {
221
  *
222
  * @section Campaign Stats
223
  *
224
- * @param string $cid the campaign id to pull stats for (can be gathered using campaigns($id))
 
 
 
225
  * @return array struct of the statistics for this campaign
226
  * @returnf integer syntax_errors Number of email addresses in campaign that had syntactical errors.
227
  * @returnf integer hard_bounces Number of email addresses in campaign that hard bounced.
@@ -250,8 +460,11 @@ class MCAPI {
250
  *
251
  * @section Campaign Stats
252
  *
253
- * @param string $cid the campaign id to pull stats for (can be gathered using campaigns($id))
254
- * @return struct list of urls and their associated statistics
 
 
 
255
  * @returnf integer clicks Number of times the specific link was clicked
256
  * @returnf integer unique Number of unique people who clicked on the specific link
257
  */
@@ -262,22 +475,33 @@ class MCAPI {
262
  }
263
 
264
  /**
265
- * Get all bounced email addresses for a given campaign<br/>
266
- * <strong>DEPRECATED:</strong> campaignBounces() has been deprecated and will be removed completely in a future release. see campaignHardBounces() and campaignSoftBounces() for replacements.
267
- *
268
  * @section Campaign Stats
269
  *
270
- * @deprecated See campaignHardBounces() and campaignSoftBounces() for replacements
271
- * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns($id))
272
- * @return struct Struct of arrays of bounced email addresses (hard and soft)
273
- * @returnf array hard Array of all email addresses that had Hard bounces for this campaign
274
- * @returnf array soft Array of all email addresses that had Soft bounces for this campaign
275
- * @returnf array syntax Array of all email addresses that had syntax errors in them (historical - always empty)
 
 
 
 
 
 
 
 
 
 
 
276
  */
277
- function campaignBounces($cid) {
278
  $params = array();
279
  $params["cid"] = $cid;
280
- return $this->callServer("campaignBounces", $params);
281
  }
282
 
283
  /**
@@ -285,9 +509,9 @@ class MCAPI {
285
  *
286
  * @section Campaign Stats
287
  *
288
- * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns($id))
289
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
290
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
291
  * @return array Arrays of email addresses with Hard Bounces
292
  */
293
  function campaignHardBounces($cid, $start=0, $limit=1000) {
@@ -303,9 +527,9 @@ class MCAPI {
303
  *
304
  * @section Campaign Stats
305
  *
306
- * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns($id))
307
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
308
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
309
  * @return array Arrays of email addresses with Soft Bounces
310
  */
311
  function campaignSoftBounces($cid, $start=0, $limit=1000) {
@@ -321,9 +545,9 @@ class MCAPI {
321
  *
322
  * @section Campaign Stats
323
  *
324
- * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns($id))
325
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
326
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
327
  * @return array list of email addresses that unsubscribed from this campaign
328
  */
329
  function campaignUnsubscribes($cid, $start=0, $limit=1000) {
@@ -339,43 +563,155 @@ class MCAPI {
339
  *
340
  * @section Campaign Stats
341
  *
342
- * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns($id))
343
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
344
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
345
- * @return array list of email addresses that complained (filed abuse reports) about this campaign
 
 
 
 
 
 
346
  */
347
- function campaignAbuseReports($cid, $start=0, $limit=1000) {
348
  $params = array();
349
  $params["cid"] = $cid;
 
350
  $params["start"] = $start;
351
  $params["limit"] = $limit;
352
  return $this->callServer("campaignAbuseReports", $params);
353
  }
354
 
355
  /**
356
- * Get the content (both html and text) for a campaign, exactly as it would appear in the campaign archive
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
357
  *
358
  * @section Campaign Related
359
  *
360
- * @param string $cid the campaign id to get content for (can be gathered using campaigns($id))
 
361
  * @return struct Struct containing all content for the campaign (see Returned Fields for details
362
  * @returnf string html The HTML content used for the campgain with merge tags intact
363
  * @returnf string text The Text content used for the campgain with merge tags intact
364
  */
365
- function campaignContent($cid) {
366
  $params = array();
367
  $params["cid"] = $cid;
 
368
  return $this->callServer("campaignContent", $params);
369
  }
370
 
371
  /**
372
- * Retrieve the list of email addresses that opened a given campaign with how many times they opened
 
373
  *
374
  * @section Campaign AIM
375
  *
376
- * @param string $cid the campaign id to get opens for (can be gathered using campaigns($id))
377
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
378
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
379
  * @return array Array of structs containing email addresses and open counts
380
  * @returnf string email Email address that opened the campaign
381
  * @returnf integer open_count Total number of times the campaign was opened by this email address
@@ -393,9 +729,9 @@ class MCAPI {
393
  *
394
  * @section Campaign AIM
395
  *
396
- * @param string $cid the campaign id to get no opens for (can be gathered using campaigns($id))
397
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
398
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
399
  * @return array list of email addresses that did not open a campaign
400
  */
401
  function campaignNotOpenedAIM($cid, $start=0, $limit=1000) {
@@ -411,10 +747,10 @@ class MCAPI {
411
  *
412
  * @section Campaign AIM
413
  *
414
- * @param string $cid the campaign id to get click stats for (can be gathered using campaigns($id))
415
  * @param string $url the URL of the link that was clicked on
416
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
417
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
418
  * @return array Array of structs containing email addresses and click counts
419
  * @returnf string email Email address that opened the campaign
420
  * @returnf integer clicks Total number of times the URL was clicked on by this email address
@@ -433,9 +769,8 @@ class MCAPI {
433
  *
434
  * @section Campaign AIM
435
  *
436
- * @param string $cid the campaign id to get stats for (can be gathered using campaigns($id))
437
- * @param string $email_address the email address to get activity history for
438
- * @return array Array of structs containing actions (opens and clicks) that the email took, with timestamps
439
  * @returnf string action The action taken (open or click)
440
  * @returnf date timestamp Time the action occurred
441
  * @returnf string url For clicks, the URL that was clicked
@@ -447,17 +782,82 @@ class MCAPI {
447
  return $this->callServer("campaignEmailStatsAIM", $params);
448
  }
449
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
450
  /**
451
  * Retrieve all of the lists defined for your user account
452
  *
453
  * @section List Related
 
454
  * @example xml-rpc_lists.php
455
  *
456
  * @return array list of your Lists and their associated information (see Returned Fields for description)
457
  * @returnf string id The list id for this list. This will be used for all other list management functions.
 
458
  * @returnf string name The name of the list.
459
  * @returnf date date_created The date that this list was created.
460
  * @returnf integer member_count The number of active members in the given list.
 
 
 
 
 
 
 
461
  */
462
  function lists() {
463
  $params = array();
@@ -468,8 +868,9 @@ class MCAPI {
468
  * Get the list of merge tags for a given list, including their name, tag, and required setting
469
  *
470
  * @section List Related
 
471
  *
472
- * @param string $id the list id to connect to
473
  * @return array list of merge tags for the list
474
  * @returnf string name Name of the merge field
475
  * @returnf char req Denotes whether the field is required (Y) or not (N)
@@ -481,12 +882,78 @@ class MCAPI {
481
  return $this->callServer("listMergeVars", $params);
482
  }
483
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
484
  /**
485
  * Get the list of interest groups for a given list, including the label and form information
486
  *
487
  * @section List Related
 
488
  *
489
- * @param string $id the list id to connect to
490
  * @return struct list of interest groups for the list
491
  * @returnf string name Name for the Interest groups
492
  * @returnf string form_field Gives the type of interest group: checkbox,radio,select
@@ -498,28 +965,164 @@ class MCAPI {
498
  return $this->callServer("listInterestGroups", $params);
499
  }
500
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
501
  /**
502
- * Subscribe the provided email to a list
503
  *
504
  * @section List Related
505
  *
506
  * @example mcapi_listSubscribe.php
507
  * @example xml-rpc_listSubscribe.php
508
  *
509
- * @param string $id the list id to connect to
510
  * @param string $email_address the email address to subscribe
511
- * @param array $merge_vars array of merges for the email (FNAME, LNAME, etc.) (see examples below for handling "blank" arrays)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
512
  * @param string $email_type optional - email type preference for the email (html or text, defaults to html)
513
- * @param boolean $double_optin optional - flag to control whether a double opt-in confirmation message is sent, defaults to true
 
 
 
 
514
  * @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)
515
  */
516
- function listSubscribe($id, $email_address, $merge_vars, $email_type='html', $double_optin=true) {
517
  $params = array();
518
  $params["id"] = $id;
519
  $params["email_address"] = $email_address;
520
  $params["merge_vars"] = $merge_vars;
521
  $params["email_type"] = $email_type;
522
  $params["double_optin"] = $double_optin;
 
 
 
523
  return $this->callServer("listSubscribe", $params);
524
  }
525
 
@@ -528,8 +1131,9 @@ class MCAPI {
528
  *
529
  * @section List Related
530
  * @example mcapi_listUnsubscribe.php
 
531
  *
532
- * @param string $id the list id to connect to
533
  * @param string $email_address the email address to unsubscribe
534
  * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
535
  * @param boolean $send_goodbye flag to send the goodbye email to the email address, defaults to true
@@ -550,8 +1154,9 @@ class MCAPI {
550
  * Edit the email address, merge fields, and interest groups for a list member
551
  *
552
  * @section List Related
 
553
  *
554
- * @param string $id the list id to connect to
555
  * @param string $email_address the current email address of the member to update
556
  * @param array $merge_vars array of new field values to update the member with. Use "EMAIL" to update the email address and "INTERESTS" to update the interest groups
557
  * @param string $email_type change the email type preference for the member ("html" or "text"). Leave blank to keep the existing preference (optional)
@@ -572,9 +1177,11 @@ class MCAPI {
572
  * Subscribe a batch of email addresses to a list at once
573
  *
574
  * @section List Related
 
 
575
  * @example xml-rpc_listBatchSubscribe.php
576
  *
577
- * @param string $id the list id to connect to
578
  * @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 or text)
579
  * @param boolean $double_optin flag to control whether to send an opt-in confirmation email - defaults to true
580
  * @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)
@@ -582,7 +1189,7 @@ class MCAPI {
582
  * @return struct Array of result counts and any errors that occurred
583
  * @returnf integer success_count Number of email addresses that were succesfully added/updated
584
  * @returnf integer error_count Number of email addresses that failed during addition/updating
585
- * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and "email_address"
586
  */
587
  function listBatchSubscribe($id, $batch, $double_optin=true, $update_existing=false, $replace_interests=true) {
588
  $params = array();
@@ -598,8 +1205,9 @@ class MCAPI {
598
  * Unsubscribe a batch of email addresses to a list
599
  *
600
  * @section List Related
 
601
  *
602
- * @param string $id the list id to connect to
603
  * @param array $emails array of email addresses to unsubscribe
604
  * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
605
  * @param boolean $send_goodbye flag to send the goodbye email to the email addresses, defaults to true
@@ -607,7 +1215,7 @@ class MCAPI {
607
  * @return struct Array of result counts and any errors that occurred
608
  * @returnf integer success_count Number of email addresses that were succesfully added/updated
609
  * @returnf integer error_count Number of email addresses that failed during addition/updating
610
- * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and "email_address"
611
  */
612
  function listBatchUnsubscribe($id, $emails, $delete_member=false, $send_goodbye=true, $send_notify=false) {
613
  $params = array();
@@ -620,23 +1228,25 @@ class MCAPI {
620
  }
621
 
622
  /**
623
- * Get all of the list members of a list that are of a particular status
624
  *
625
  * @section List Related
626
  * @example mcapi_listMembers.php
627
  *
628
- * @param string $id the list id to connect to
629
- * @param string $status the status to get members for - one of(subscribed, unsubscribed, or cleaned), defaults to subscribed
630
- * @param int $start optional, for large data sets, the page number to start at - defaults to 1st page of data
631
- * @param int $limit optional, for large data sets, the number of results to return - defaults to 100, upper limit set at 15000
 
632
  * @return array Array of list member structs (see Returned Fields for details)
633
  * @returnf string email Member email address
634
- * @returnf date timestamp timestamp of their associated status(date subscribed, unsubscribed, or cleaned)
635
  */
636
- function listMembers($id, $status='subscribed', $start=0, $limit=100) {
637
  $params = array();
638
  $params["id"] = $id;
639
  $params["status"] = $status;
 
640
  $params["start"] = $start;
641
  $params["limit"] = $limit;
642
  return $this->callServer("listMembers", $params);
@@ -647,13 +1257,18 @@ class MCAPI {
647
  *
648
  * @section List Related
649
  * @example mcapi_listMemberInfo.php
650
- * @param string $id the list id to connect to
 
 
651
  * @param string $email_address the member email address to get information for
652
  * @return array array of list member info (see Returned Fields for details)
653
  * @returnf string email The email address associated with this record
654
  * @returnf string email_type The type of emails this customer asked to get: html or text
655
- * @returnf array merges An associative array of all the merge tags and the data for those tags for this email address
656
  * @returnf string status The subscription status for this email address, either subscribed, unsubscribed or cleaned
 
 
 
657
  * @returnf date timestamp The time this email address was added to the list
658
  */
659
  function listMemberInfo($id, $email_address) {
@@ -663,6 +1278,230 @@ class MCAPI {
663
  return $this->callServer("listMemberInfo", $params);
664
  }
665
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
666
  /**
667
  * Internal function - proxy method for certain XML-RPC calls | DO NOT CALL
668
  * @param mixed Method to call, with any parameters to pass along
@@ -678,25 +1517,36 @@ class MCAPI {
678
  * You should never have to call this function manually
679
  */
680
  function callServer($method, $params) {
681
- //Always include the user id if we're not loggin in
682
  if($method != "login") {
683
- $params["uid"] = $this->uuid;
 
 
 
 
 
684
  }
685
-
 
686
  $post_vars = $this->httpBuildQuery($params);
687
 
688
  $payload = "POST " . $this->apiUrl["path"] . "?" . $this->apiUrl["query"] . "&method=" . $method . " HTTP/1.0\r\n";
689
- $payload .= "Host: " . $this->apiUrl["host"] . "\r\n";
 
690
  $payload .= "Content-type: application/x-www-form-urlencoded\r\n";
691
  $payload .= "Content-length: " . strlen($post_vars) . "\r\n";
692
  $payload .= "Connection: close \r\n\r\n";
693
  $payload .= $post_vars;
694
 
695
  ob_start();
696
- $sock = fsockopen($this->apiUrl["host"], 80, $errno, $errstr, $this->timeout);
 
 
 
 
697
  if(!$sock) {
698
  $this->errorMessage = "Could not connect (ERR $errno: $errstr)";
699
- $this->errorCode = "SERVER_ERROR";
700
  ob_end_clean();
701
  return false;
702
  }
@@ -715,7 +1565,7 @@ class MCAPI {
715
 
716
  $serial = unserialize($response);
717
  if($response && $serial === false) {
718
- $response = array("error" => "Bad Response. Got This: " . $response, "code" => "SERVER_ERROR");
719
  } else {
720
  $response = $serial;
721
  }
1
  <?php
2
 
3
  class MCAPI {
4
+ var $version = "1.2";
5
  var $errorMessage;
6
  var $errorCode;
7
 
21
  var $chunkSize = 8192;
22
 
23
  /**
24
+ * Cache the user api_key so we only have to log in once per client instantiation
25
  */
26
+ var $api_key;
27
+
28
+ /**
29
+ * Cache the user api_key so we only have to log in once per client instantiation
30
+ */
31
+ var $secure = false;
32
 
33
  /**
34
  * Connect to the MailChimp API for a given list. All MCAPI calls require login before functioning
35
  *
36
+ * @param string $username_or_apikey Your MailChimp login user name OR apikey - always required
37
+ * @param string $password Your MailChimp login password - only required when username passed instead of API Key
38
  */
39
+ function MCAPI($username_or_apikey, $password=null, $secure=false) {
40
+ //do more "caching" of the uuid for those people that keep instantiating this...
41
+ $this->secure = $secure;
42
  $this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
43
+ if ( isset($GLOBALS["mc_api_key"]) && $GLOBALS["mc_api_key"]!="" ){
44
+ $this->api_key = $GLOBALS["mc_api_key"];
45
+ } elseif( $username_or_apikey && !$password ){
46
+ $this->api_key = $GLOBALS["mc_api_key"] = $username_or_apikey;
47
+ } else {
48
+ $this->api_key = $this->callServer("login", array("username" => $username_or_apikey, "password" => $password));
49
+ $GLOBALS["mc_api_key"] = $this->api_key;
50
+ }
51
  }
52
+ function setTimeout($seconds){
53
+ if (is_int($seconds)){
54
+ $this->timeout = $seconds;
55
+ return true;
56
+ }
57
+ }
58
+ function getTimeout(){
59
+ return $this->timeout;
60
+ }
61
+ function useSecure($val){
62
+ if ($val===true){
63
+ $this->secure = true;
64
+ } else {
65
+ $this->secure = false;
66
+ }
67
+ }
68
+
69
  /**
70
  * Unschedule a campaign that is scheduled to be sent in the future
71
  *
72
  * @section Campaign Related
73
+ * @example mcapi_campaignUnschedule.php
74
  * @example xml-rpc_campaignUnschedule.php
75
  *
76
+ * @param string $cid the id of the campaign to unschedule
77
  * @return boolean true on success
78
  */
79
  function campaignUnschedule($cid) {
86
  * Schedule a campaign to be sent in the future
87
  *
88
  * @section Campaign Related
89
+ * @example mcapi_campaignSchedule.php
90
  * @example xml-rpc_campaignSchedule.php
91
  *
92
+ * @param string $cid the id of the campaign to schedule
93
+ * @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>
94
+ * @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>
95
  * @return boolean true on success
96
  */
97
+ function campaignSchedule($cid, $schedule_time, $schedule_time_b=NULL) {
98
  $params = array();
99
  $params["cid"] = $cid;
100
  $params["schedule_time"] = $schedule_time;
101
+ $params["schedule_time_b"] = $schedule_time_b;
102
  return $this->callServer("campaignSchedule", $params);
103
  }
104
 
105
+ /**
106
+ * Resume sending an AutoResponder or RSS campaign
107
+ *
108
+ * @section Campaign Related
109
+ *
110
+ * @param string $cid the id of the campaign to pause
111
+ * @return boolean true on success
112
+ */
113
+ function campaignResume($cid) {
114
+ $params = array();
115
+ $params["cid"] = $cid;
116
+ return $this->callServer("campaignResume", $params);
117
+ }
118
+
119
+ /**
120
+ * Pause an AutoResponder orRSS campaign from sending
121
+ *
122
+ * @section Campaign Related
123
+ *
124
+ * @param string $cid the id of the campaign to pause
125
+ * @return boolean true on success
126
+ */
127
+ function campaignPause($cid) {
128
+ $params = array();
129
+ $params["cid"] = $cid;
130
+ return $this->callServer("campaignPause", $params);
131
+ }
132
+
133
  /**
134
  * Send a given campaign immediately
135
  *
136
  * @section Campaign Related
 
137
  *
138
+ * @example mcapi_campaignSendNow.php
139
+ * @example xml-rpc_campaignSendNow.php
140
+ *
141
+ * @param string $cid the id of the campaign to resume
142
  * @return boolean true on success
143
  */
144
  function campaignSendNow($cid) {
151
  * Send a test of this campaign to the provided email address
152
  *
153
  * @section Campaign Related
154
+ *
155
+ * @example mcapi_campaignSendTest.php
156
  * @example xml-rpc_campaignSendTest.php
157
  *
158
+ * @param string $cid the id of the campaign to test
159
+ * @param array $test_emails an array of email address to receive the test message
160
+ * @param string $send_type optional by default (null) both formats are sent - "html" or "text" send just that format
161
  * @return boolean true on success
162
  */
163
  function campaignSendTest($cid, $test_emails=array (
173
  * Retrieve all templates defined for your user account
174
  *
175
  * @section Campaign Related
176
+ * @example mcapi_campaignTemplates.php
177
  * @example xml-rpc_campaignTemplates.php
178
  *
179
  * @return array An array of structs, one for each template (see Returned Fields for details)
187
  return $this->callServer("campaignTemplates", $params);
188
  }
189
 
190
+ /**
191
+ * Allows one to test their segmentation rules before creating a campaign using them
192
+ *
193
+ * @section Campaign Related
194
+ * @example mcapi_campaignSegmentTest.php
195
+ * @example xml-rpc_campaignSegmentTest.php
196
+ *
197
+ * @param string $list_id the list to test segmentation on - get lists using lists()
198
+ * @param array $options with 2 keys:
199
+ 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)
200
+ array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row should contain 3 keys - "<strong>field</strong>", "<strong>op</strong>", or "<strong>value</strong>" based on these definitions:
201
+
202
+ Field = "<strong>date</strong>" : Select based on various dates we track
203
+ Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
204
+ Valid Values:
205
+ string last_campaign_sent uses the date of the last campaign sent
206
+ string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns()
207
+ string YYYY-MM-DD - ny date in the form of YYYY-MM-DD - <em>note:</em> anything that appears to start with YYYY will be treated as a date
208
+
209
+ Field = "<strong>interests</strong>":
210
+ Valid Op(erations): <strong>one</strong> / <strong>none</strong> / <strong>all</strong>
211
+ Valid Values: a comma delimited of interest groups for the list - see listInterestGroups()
212
+
213
+ Field = "<strong>aim</strong>"
214
+ Valid Op(erations): <strong>open</strong> / <strong>noopen</strong> / <strong>click</strong> / <strong>noclick</strong>
215
+ Valid Values: "<strong>any</strong>" or a valid AIM-enabled Campaign that has been sent
216
+
217
+ 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()
218
+ Valid Op(erations):
219
+ <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')
220
+ Valid Values: any string
221
+ * @return integer total The total number of subscribers matching your segmentation options
222
+ */
223
+ function campaignSegmentTest($list_id, $options) {
224
+ $params = array();
225
+ $params["list_id"] = $list_id;
226
+ $params["options"] = $options;
227
+ return $this->callServer("campaignSegmentTest", $params);
228
+ }
229
+
230
  /**
231
  * Create a new draft campaign to send
232
  *
233
  * @section Campaign Related
234
+ * @example mcapi_campaignCreate.php
235
+ * @example xml-rpc_campaignCreate.php
236
+ * @example xml-rpc_campaignCreateABSplit.php
237
+ * @example xml-rpc_campaignCreateRss.php
238
+ *
239
+ * @param string $type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "trans", "auto"
240
+ * @param array $options a hash of the standard options for this campaign :
241
+ string list_id the list to send this campaign to- get lists using lists()
242
+ string subject the subject line for your campaign message
243
+ string from_email the From: email address for your campaign message
244
+ string from_name the From: name for your campaign message (not an email address)
245
+ string to_email the To: name recipients will see (not email address)
246
+ integer template_id optional - use this template to generate the HTML content of the campaign
247
+ integer folder_id optional - automatically file the new campaign in the folder_id passed
248
+ 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.
249
+ string title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
250
+ boolean authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
251
+ 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
252
+ boolean auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
253
+ boolean inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
254
+ 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.
255
+
256
+ * @param array $content the content for this campaign - use a struct with the following keys:
257
+ "html" for pasted HTML content
258
+ "text" for the plain-text version
259
+ "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
260
+ "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
261
+ "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
262
+
263
+
264
+ 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"
265
+ * @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.
266
+ * @param array $type_opts optional -
267
+ For RSS Campaigns this, array should contain:
268
+ string url the URL to pull RSS content from - it will be verified and must exist
269
+
270
+ For A/B Split campaigns, this array should contain:
271
+ 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!
272
+ 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)
273
+ integer wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
274
+ integer 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.
275
+ integer 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%
276
+ string from_name_a optional sort of, required when split_test is "from_name"
277
+ string from_name_b optional sort of, required when split_test is "from_name"
278
+ string from_email_a optional sort of, required when split_test is "from_name"
279
+ string from_email_b optional sort of, required when split_test is "from_name"
280
+ string subject_a optional sort of, required when split_test is "subject"
281
+ string subject_b optional sort of, required when split_test is "subject"
282
+
283
+ For AutoResponder campaigns, this array should contain:
284
+ string offset-units one of "day", "week", "month", "year" - required
285
+ string offset-time the number of units, must be a number greater than 0 - required
286
+ string offset-dir either "before" or "after"
287
+ string event optional "signup" (default) to base this on double-optin signup, "date" or "annual" to base this on merge field in the list
288
+ string event-datemerge optional sort of, this is required if the event is "date" or "annual"
289
+
290
+ *
291
  * @return string the ID for the created campaign
292
  */
293
+ function campaignCreate($type, $options, $content, $segment_opts=NULL, $type_opts=NULL) {
 
 
 
 
294
  $params = array();
295
+ $params["type"] = $type;
296
+ $params["options"] = $options;
 
 
297
  $params["content"] = $content;
298
+ $params["segment_opts"] = $segment_opts;
299
+ $params["type_opts"] = $type_opts;
 
 
 
300
  return $this->callServer("campaignCreate", $params);
301
  }
302
 
303
+ /** Update just about any setting for a campaign that has <em>not</em> been sent. See campaignCreate() for details
304
+ *
305
+ * Caveats:<br/><ul>
306
+ * <li>If you set list_id, all segmentation options will be deleted and must be re-added.</li>
307
+ * <li>If you set template_id, you need to follow that up by setting it's 'content'</li>
308
+ * <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>
309
+ * @section Campaign Related
310
+ *
311
+ * @example mcapi_campaignUpdate.php
312
+ * @example mcapi_campaignUpdateAB.php
313
+ * @example xml-rpc_campaignUpdate.php
314
+ * @example xml-rpc_campaignUpdateAB.php
315
+ *
316
+ * @param string $cid the Campaign Id to update
317
+ * @param string $name the parameter name ( see campaignCreate() )
318
+ * @param mixed $value an appropriate value for the parameter ( see campaignCreate() )
319
+ * @return boolean true if the update succeeds, otherwise an error will be thrown
320
+ */
321
+ function campaignUpdate($cid, $name, $value) {
322
+ $params = array();
323
+ $params["cid"] = $cid;
324
+ $params["name"] = $name;
325
+ $params["value"] = $value;
326
+ return $this->callServer("campaignUpdate", $params);
327
+ }
328
+
329
+ /** Replicate a campaign.
330
+ *
331
+ * @section Campaign Related
332
+ *
333
+ * @example mcapi_campaignReplicate.php
334
+ *
335
+ * @param string $cid the Campaign Id to replicate
336
+ * @return string the id of the replicated Campaign created, otherwise an error will be thrown
337
+ */
338
+ function campaignReplicate($cid) {
339
+ $params = array();
340
+ $params["cid"] = $cid;
341
+ return $this->callServer("campaignReplicate", $params);
342
+ }
343
+
344
+ /** Delete a campaign. Seriously, "poof, gone!" - be careful!
345
+ *
346
+ * @section Campaign Related
347
+ *
348
+ * @example mcapi_campaignDelete.php
349
+ *
350
+ * @param string $cid the Campaign Id to delete
351
+ * @return boolean true if the delete succeeds, otherwise an error will be thrown
352
+ */
353
+ function campaignDelete($cid) {
354
+ $params = array();
355
+ $params["cid"] = $cid;
356
+ return $this->callServer("campaignDelete", $params);
357
+ }
358
+
359
  /**
360
+ * Get the list of campaigns and their details matching the specified filters
361
  *
362
  * @section Campaign Related
363
+ * @example mcapi_campaigns.php
364
+ * @example xml-rpc_campaigns.php
365
  *
366
+ * @param array $filters a hash of filters to apply to this query - all are optional:
367
+ string campaign_id optional - return a single campaign using a know campaign_id
368
+ string list_id optional - the list to send this campaign to- get lists using lists()
369
+ integer folder_id optional - only show campaigns from this folder id - get folders using campaignFolders()
370
+ string type optional - return campaigns of a specific type - one of "regular", "plaintext", "absplit", "rss", "trans", "auto"
371
+ string from_name optional - only show campaigns that have this "From Name"
372
+ string from_email optional - only show campaigns that have this "Reply-to Email"
373
+ string title optional - only show campaigns that have this title
374
+ string subject optional - only show campaigns that have this subject
375
+ 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)
376
+ 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)
377
+ boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true
378
+ * @param integer $start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data (page 0)
379
+ * @param integer $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=1000)
380
  * @return array list of campaigns and their associated information (see Returned Fields for description)
381
  * @returnf string id Campaign Id (used for all other campaign functions)
382
+ * @returnf integer web_id The Campaign id used in our web app, allows you to create a link directly to it
383
  * @returnf string title Title of the campaign
384
+ * @returnf string type The type of campaign this is (regular,plaintext,absplit,rss,inspection,trans,auto)
385
  * @returnf date create_time Creation time for the campaign
386
  * @returnf date send_time Send time for the campaign
387
+ * @returnf integer emails_sent Number of emails email was sent to
388
+ * @returnf string status Status of the given campaign (save,paused,schedule,sending,sent)
389
  * @returnf string from_name From name of the given campaign
390
  * @returnf string from_email Reply-to email of the given campaign
391
  * @returnf string subject Subject of the given campaign
392
+ * @returnf string to_email Custom "To:" email string using merge variables
393
  * @returnf string archive_url Archive link for the given campaign
394
+ * @returnf boolean inline_css Whether or not the campaigns content auto-css-lined
395
+ * @returnf string analytics Either "google" if enabled or "N" if disabled
396
+ * @returnf string analytcs_tag The name/tag the campaign's links were tagged with if analytics were enabled.
397
+ * @returnf boolean track_clicks_text Whether or not links in the text version of the campaign were tracked
398
+ * @returnf boolean track_clicks_html Whether or not links in the html version of the campaign were tracked
399
+ * @returnf boolean track_opens Whether or not opens for the campaign were tracked
400
  */
401
+ function campaigns($filters=array (
402
+ ), $start=0, $limit=25) {
403
+ $params = array();
404
+ $params["filters"] = $filters;
 
 
 
 
 
 
 
405
  $params["start"] = $start;
406
  $params["limit"] = $limit;
407
  return $this->callServer("campaigns", $params);
411
  * List all the folders for a user account
412
  *
413
  * @section Campaign Related
414
+ * @example mcapi_campaignFolders.php
415
+ * @example xml-rpc_campaignFolders.php
416
  *
417
  * @return array Array of folder structs (see Returned Fields for details)
418
  * @returnf integer folder_id Folder Id for the given folder, this can be used in the campaigns() function to filter on.
428
  *
429
  * @section Campaign Stats
430
  *
431
+ * @example mcapi_campaignStats.php
432
+ * @example xml-rpc_campaignStats.php
433
+ *
434
+ * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
435
  * @return array struct of the statistics for this campaign
436
  * @returnf integer syntax_errors Number of email addresses in campaign that had syntactical errors.
437
  * @returnf integer hard_bounces Number of email addresses in campaign that hard bounced.
460
  *
461
  * @section Campaign Stats
462
  *
463
+ * @example mcapi_campaignClickStats.php
464
+ * @example xml-rpc_campaignClickStats.php
465
+ *
466
+ * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
467
+ * @return struct urls will be keys and contain their associated statistics:
468
  * @returnf integer clicks Number of times the specific link was clicked
469
  * @returnf integer unique Number of unique people who clicked on the specific link
470
  */
475
  }
476
 
477
  /**
478
+ * Get the top 5 performing email domains for this campaign. Users want more than 5 should use campaign campaignEmailStatsAIM()
479
+ * or campaignEmailStatsAIMAll() and generate any additional stats they require.
480
+ *
481
  * @section Campaign Stats
482
  *
483
+ * @example mcapi_campaignEmailDomainPerformance.php
484
+ *
485
+ * @param string $cid the campaign id to pull email domain performance for (can be gathered using campaigns())
486
+ * @return array domains email domains and their associated stats
487
+ * @returnf string domain Domain name or special "Other" to roll-up stats past 5 domains
488
+ * @returnf integer total_sent Total Email across all domains - this will be the same in every row
489
+ * @returnf integer emails Number of emails sent to this domain
490
+ * @returnf integer bounces Number of bounces
491
+ * @returnf integer opens Number of opens
492
+ * @returnf integer clicks Number of clicks
493
+ * @returnf integer unsubs Number of unsubs
494
+ * @returnf integer delivered Number of deliveries
495
+ * @returnf integer emails_pct Percentage of emails that went to this domain (whole number)
496
+ * @returnf integer bounces_pct Percentage of bounces from this domain (whole number)
497
+ * @returnf integer opens_pct Percentage of opens from this domain (whole number)
498
+ * @returnf integer clicks_pct Percentage of clicks from this domain (whole number)
499
+ * @returnf integer unsubs_pct Percentage of unsubs from this domain (whole number)
500
  */
501
+ function campaignEmailDomainPerformance($cid) {
502
  $params = array();
503
  $params["cid"] = $cid;
504
+ return $this->callServer("campaignEmailDomainPerformance", $params);
505
  }
506
 
507
  /**
509
  *
510
  * @section Campaign Stats
511
  *
512
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
513
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
514
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
515
  * @return array Arrays of email addresses with Hard Bounces
516
  */
517
  function campaignHardBounces($cid, $start=0, $limit=1000) {
527
  *
528
  * @section Campaign Stats
529
  *
530
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
531
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
532
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
533
  * @return array Arrays of email addresses with Soft Bounces
534
  */
535
  function campaignSoftBounces($cid, $start=0, $limit=1000) {
545
  *
546
  * @section Campaign Stats
547
  *
548
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
549
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
550
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
551
  * @return array list of email addresses that unsubscribed from this campaign
552
  */
553
  function campaignUnsubscribes($cid, $start=0, $limit=1000) {
563
  *
564
  * @section Campaign Stats
565
  *
566
+ * @example mcapi_campaignAbuseReports.php
567
+ *
568
+ * @param string $cid the campaign id to pull abuse reports for (can be gathered using campaigns())
569
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
570
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
571
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
572
+ * @return array reports the abuse reports for this campaign
573
+ * @returnf string date date/time the abuse report was received and processed
574
+ * @returnf string email the email address that reported abuse
575
+ * @returnf string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
576
  */
577
+ function campaignAbuseReports($cid, $since=NULL, $start=0, $limit=500) {
578
  $params = array();
579
  $params["cid"] = $cid;
580
+ $params["since"] = $since;
581
  $params["start"] = $start;
582
  $params["limit"] = $limit;
583
  return $this->callServer("campaignAbuseReports", $params);
584
  }
585
 
586
  /**
587
+ * Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
588
+ * suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
589
+ *
590
+ * @section Campaign Stats
591
+ *
592
+ * @example mcapi_campaignAdvice.php
593
+ *
594
+ * @param string $cid the campaign id to pull advice text for (can be gathered using campaigns())
595
+ * @return array advice on the campaign's performance
596
+ * @returnf msg the advice message
597
+ * @returnf type the "type" of the message. one of: negative, positive, or neutral
598
+ */
599
+ function campaignAdvice($cid) {
600
+ $params = array();
601
+ $params["cid"] = $cid;
602
+ return $this->callServer("campaignAdvice", $params);
603
+ }
604
+
605
+ /**
606
+ * Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
607
+ *
608
+ * @section Campaign Stats
609
+ *
610
+ * @example mcapi_campaignAnalytics.php
611
+ *
612
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
613
+ * @return array analytics we've collected for the passed campaign.
614
+ * @returnf integer visits number of visits
615
+ * @returnf integer pages number of page views
616
+ * @returnf integer new_visits new visits recorded
617
+ * @returnf integer bounces vistors who "bounced" from your site
618
+ * @returnf double time_on_site
619
+ * @returnf integer goal_conversions number of goals converted
620
+ * @returnf double goal_value value of conversion in dollars
621
+ * @returnf double revenue revenue generated by campaign
622
+ * @returnf integer transactions number of transactions tracked
623
+ * @returnf integer ecomm_conversions number Ecommerce transactions tracked
624
+ * @returnf array goals an array containing goal names and number of conversions
625
+ */
626
+ function campaignAnalytics($cid) {
627
+ $params = array();
628
+ $params["cid"] = $cid;
629
+ return $this->callServer("campaignAnalytics", $params);
630
+ }
631
+
632
+ /**
633
+ * Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
634
+ * of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
635
+ * message over 30 days old are subject to being removed
636
+ *
637
+ * @section Campaign Stats
638
+ *
639
+ * @example mcapi_campaignBounceMessages.php
640
+ *
641
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
642
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
643
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 50
644
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
645
+ * @return array bounces the full bounce messages for this campaign
646
+ * @returnf string date date/time the bounce was received and processed
647
+ * @returnf string email the email address that bounced
648
+ * @returnf string message the entire bounce message received
649
+ */
650
+ function campaignBounceMessages($cid, $start=0, $limit=25, $since=NULL) {
651
+ $params = array();
652
+ $params["cid"] = $cid;
653
+ $params["start"] = $start;
654
+ $params["limit"] = $limit;
655
+ $params["since"] = $since;
656
+ return $this->callServer("campaignBounceMessages", $params);
657
+ }
658
+
659
+ /**
660
+ * Retrieve the Ecommerce Orders tracked by campaignEcommAddOrder()
661
+ *
662
+ * @section Campaign Stats
663
+ *
664
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
665
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
666
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
667
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
668
+ * @return array orders the orders and their details that we've collected for this campaign
669
+ * @returnf store_id string the store id generated by the plugin used to uniquely identify a store
670
+ * @returnf store_name string the store name collected by the plugin - often the domain name
671
+ * @returnf order_id string the internal order id the store tracked this order by
672
+ * @returnf email string the email address that received this campaign and is associated with this order
673
+ * @returnf order_total double the order total
674
+ * @returnf tax_total double the total tax for the order (if collected)
675
+ * @returnf ship_total double the shipping total for the order (if collected)
676
+ * @returnf order_date string the date the order was tracked - from the store if possible, otherwise the GMT time we recieved it
677
+ * @returnf lines array containing detail of the order - product, category, quantity, item cost
678
+ */
679
+ function campaignEcommOrders($cid, $start=0, $limit=100, $since=NULL) {
680
+ $params = array();
681
+ $params["cid"] = $cid;
682
+ $params["start"] = $start;
683
+ $params["limit"] = $limit;
684
+ $params["since"] = $since;
685
+ return $this->callServer("campaignEcommOrders", $params);
686
+ }
687
+
688
+ /**
689
+ * 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
690
  *
691
  * @section Campaign Related
692
  *
693
+ * @param string $cid the campaign id to get content for (can be gathered using campaigns())
694
+ * @param bool $for_archive optional controls whether we return the Archive version (true) or the Raw version (false), defaults to true
695
  * @return struct Struct containing all content for the campaign (see Returned Fields for details
696
  * @returnf string html The HTML content used for the campgain with merge tags intact
697
  * @returnf string text The Text content used for the campgain with merge tags intact
698
  */
699
+ function campaignContent($cid, $for_archive=true) {
700
  $params = array();
701
  $params["cid"] = $cid;
702
+ $params["for_archive"] = $for_archive;
703
  return $this->callServer("campaignContent", $params);
704
  }
705
 
706
  /**
707
+ * 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
708
+ * not actually require the AIM module to be installed
709
  *
710
  * @section Campaign AIM
711
  *
712
+ * @param string $cid the campaign id to get opens for (can be gathered using campaigns())
713
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
714
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
715
  * @return array Array of structs containing email addresses and open counts
716
  * @returnf string email Email address that opened the campaign
717
  * @returnf integer open_count Total number of times the campaign was opened by this email address
729
  *
730
  * @section Campaign AIM
731
  *
732
+ * @param string $cid the campaign id to get no opens for (can be gathered using campaigns())
733
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
734
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
735
  * @return array list of email addresses that did not open a campaign
736
  */
737
  function campaignNotOpenedAIM($cid, $start=0, $limit=1000) {
747
  *
748
  * @section Campaign AIM
749
  *
750
+ * @param string $cid the campaign id to get click stats for (can be gathered using campaigns())
751
  * @param string $url the URL of the link that was clicked on
752
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
753
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
754
  * @return array Array of structs containing email addresses and click counts
755
  * @returnf string email Email address that opened the campaign
756
  * @returnf integer clicks Total number of times the URL was clicked on by this email address
769
  *
770
  * @section Campaign AIM
771
  *
772
+ * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
773
+ * @return array Array of structs containing the actions (opens and clicks) that the email took, with timestamps
 
774
  * @returnf string action The action taken (open or click)
775
  * @returnf date timestamp Time the action occurred
776
  * @returnf string url For clicks, the URL that was clicked
782
  return $this->callServer("campaignEmailStatsAIM", $params);
783
  }
784
 
785
+ /**
786
+ * Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
787
+ * for every user a campaign was delivered to.
788
+ *
789
+ * @section Campaign AIM
790
+ * @example mcapi_campaignEmailStatsAIMAll.php
791
+ *
792
+ * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
793
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
794
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 1000
795
+ * @return array Array of structs containing actions (opens and clicks) for each email, with timestamps
796
+ * @returnf string action The action taken (open or click)
797
+ * @returnf date timestamp Time the action occurred
798
+ * @returnf string url For clicks, the URL that was clicked
799
+ */
800
+ function campaignEmailStatsAIMAll($cid, $start=0, $limit=100) {
801
+ $params = array();
802
+ $params["cid"] = $cid;
803
+ $params["start"] = $start;
804
+ $params["limit"] = $limit;
805
+ return $this->callServer("campaignEmailStatsAIMAll", $params);
806
+ }
807
+
808
+ /**
809
+ * Attach Ecommerce Order Information to a Campaign. This will generall be used by ecommerce package plugins
810
+ * <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
811
+ * @section Campaign Related
812
+ *
813
+ * @param array $order an array of information pertaining to the order that has completed. Use the following keys:
814
+ string id the Order Id
815
+ string campaign_id the Campaign Id to track this order with (see the "mc_cid" query string variable a campaign passes)
816
+ 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)
817
+ double total The Order Total (ie, the full amount the customer ends up paying)
818
+ double shipping optional the total paid for Shipping Fees
819
+ double tax optional the total tax paid
820
+ string store_id a unique id for the store sending the order in
821
+ 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)
822
+ string plugin_id the MailChimp assigned Plugin Id. Get yours by <a href="/api/register.php">registering here</a>
823
+ array items the individual line items for an order using these keys:
824
+ <div style="padding-left:30px"><table><tr><td colspan=*>
825
+ integer line_num optional the line number of the item on the order. We will generate these if they are not passed
826
+ integer product_id the store's internal Id for the product. Lines that do no contain this will be skipped
827
+ 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)
828
+ integer 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
829
+ 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.
830
+ double qty the quantity of the item ordered
831
+ double cost the cost of a single item (ie, not the extended cost of the line)
832
+ </td></tr></table></div>
833
+ * @return bool true if the data is saved, otherwise an error is thrown.
834
+ */
835
+ function campaignEcommAddOrder($order) {
836
+ $params = array();
837
+ $params["order"] = $order;
838
+ return $this->callServer("campaignEcommAddOrder", $params);
839
+ }
840
+
841
  /**
842
  * Retrieve all of the lists defined for your user account
843
  *
844
  * @section List Related
845
+ * @example mcapi_lists.php
846
  * @example xml-rpc_lists.php
847
  *
848
  * @return array list of your Lists and their associated information (see Returned Fields for description)
849
  * @returnf string id The list id for this list. This will be used for all other list management functions.
850
+ * @returnf integer web_id The list id used in our web app, allows you to create a link directly to it
851
  * @returnf string name The name of the list.
852
  * @returnf date date_created The date that this list was created.
853
  * @returnf integer member_count The number of active members in the given list.
854
+ * @returnf integer unsubscribe_count The number of members who have unsubscribed from the given list.
855
+ * @returnf integer cleaned_count The number of members cleaned from the given list.
856
+ * @returnf boolean email_type_option Whether or not the List supports multiple formats for emails or just HTML
857
+ * @returnf string default_from_name Default From Name for campaigns using this list
858
+ * @returnf string default_from_email Default From Email for campaigns using this list
859
+ * @returnf string default_subject Default Subject Line for campaigns using this list
860
+ * @returnf string default_language Default Language for this list's forms
861
  */
862
  function lists() {
863
  $params = array();
868
  * Get the list of merge tags for a given list, including their name, tag, and required setting
869
  *
870
  * @section List Related
871
+ * @example xml-rpc_listMergeVars.php
872
  *
873
+ * @param string $id the list id to connect to. Get by calling lists()
874
  * @return array list of merge tags for the list
875
  * @returnf string name Name of the merge field
876
  * @returnf char req Denotes whether the field is required (Y) or not (N)
882
  return $this->callServer("listMergeVars", $params);
883
  }
884
 
885
+ /**
886
+ * Add a new merge tag to a given list
887
+ *
888
+ * @section List Related
889
+ * @example xml-rpc_listMergeVarAdd.php
890
+ *
891
+ * @param string $id the list id to connect to. Get by calling lists()
892
+ * @param string $tag The merge tag to add, e.g. FNAME
893
+ * @param string $name The long description of the tag being added, used for user displays
894
+ * @param array $req optional Various options for this merge var. <em>note:</em> for historical purposes this can also take a "boolean"
895
+ string field_type optional one of: text, number, radio, dropdownn, date, address, phone, url, imageurl - defaults to text
896
+ boolean req optional indicates whether the field is required - defaults to false
897
+ boolean public optional indicates whether the field is displayed in public - defaults to true
898
+ boolean show optional indicates whether the field is displayed in the app's list member view - defaults to true
899
+ string default_value optional the default value for the field. See listSubscribe() for formatting info. Defaults to blank
900
+ array choices optional kind of - an array of strings to use as the choices for radio and dropdown type fields
901
+
902
+ * @return bool true if the request succeeds, otherwise an error will be thrown
903
+ */
904
+ function listMergeVarAdd($id, $tag, $name, $req=array (
905
+ )) {
906
+ $params = array();
907
+ $params["id"] = $id;
908
+ $params["tag"] = $tag;
909
+ $params["name"] = $name;
910
+ $params["req"] = $req;
911
+ return $this->callServer("listMergeVarAdd", $params);
912
+ }
913
+
914
+ /**
915
+ * Update most parameters for a merge tag on a given list. You cannot currently change the merge type
916
+ *
917
+ * @section List Related
918
+ *
919
+ * @param string $id the list id to connect to. Get by calling lists()
920
+ * @param string $tag The merge tag to update
921
+ * @param array $options The options to change for a merge var. See listMergeVarAdd() for valid options
922
+ * @return bool true if the request succeeds, otherwise an error will be thrown
923
+ */
924
+ function listMergeVarUpdate($id, $tag, $options) {
925
+ $params = array();
926
+ $params["id"] = $id;
927
+ $params["tag"] = $tag;
928
+ $params["options"] = $options;
929
+ return $this->callServer("listMergeVarUpdate", $params);
930
+ }
931
+
932
+ /**
933
+ * Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well!
934
+ * Note that on large lists this method may seem a bit slower than calls you typically make.
935
+ *
936
+ * @section List Related
937
+ * @example xml-rpc_listMergeVarDel.php
938
+ *
939
+ * @param string $id the list id to connect to. Get by calling lists()
940
+ * @param string $tag The merge tag to delete
941
+ * @return bool true if the request succeeds, otherwise an error will be thrown
942
+ */
943
+ function listMergeVarDel($id, $tag) {
944
+ $params = array();
945
+ $params["id"] = $id;
946
+ $params["tag"] = $tag;
947
+ return $this->callServer("listMergeVarDel", $params);
948
+ }
949
+
950
  /**
951
  * Get the list of interest groups for a given list, including the label and form information
952
  *
953
  * @section List Related
954
+ * @example xml-rpc_listInterestGroups.php
955
  *
956
+ * @param string $id the list id to connect to. Get by calling lists()
957
  * @return struct list of interest groups for the list
958
  * @returnf string name Name for the Interest groups
959
  * @returnf string form_field Gives the type of interest group: checkbox,radio,select
965
  return $this->callServer("listInterestGroups", $params);
966
  }
967
 
968
+ /** Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first
969
+ * group will automatically turn them on.
970
+ *
971
+ * @section List Related
972
+ * @example xml-rpc_listInterestGroupAdd.php
973
+ *
974
+ * @param string $id the list id to connect to. Get by calling lists()
975
+ * @param string $group_name the interest group to add
976
+ * @return bool true if the request succeeds, otherwise an error will be thrown
977
+ */
978
+ function listInterestGroupAdd($id, $group_name) {
979
+ $params = array();
980
+ $params["id"] = $id;
981
+ $params["group_name"] = $group_name;
982
+ return $this->callServer("listInterestGroupAdd", $params);
983
+ }
984
+
985
+ /** Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.
986
+ *
987
+ * @section List Related
988
+ * @example xml-rpc_listInterestGroupDel.php
989
+ *
990
+ * @param string $id the list id to connect to. Get by calling lists()
991
+ * @param string $group_name the interest group to delete
992
+ * @return bool true if the request succeeds, otherwise an error will be thrown
993
+ */
994
+ function listInterestGroupDel($id, $group_name) {
995
+ $params = array();
996
+ $params["id"] = $id;
997
+ $params["group_name"] = $group_name;
998
+ return $this->callServer("listInterestGroupDel", $params);
999
+ }
1000
+
1001
+ /** Change the name of an Interest Group
1002
+ *
1003
+ * @section List Related
1004
+ * @example xml-rpc_listInterestGroupDel.php
1005
+ *
1006
+ * @param string $id the list id to connect to. Get by calling lists()
1007
+ * @param string $old_name the interest group name to be changed
1008
+ * @param string $new_name the new interest group name to be set
1009
+ * @return bool true if the request succeeds, otherwise an error will be thrown
1010
+ */
1011
+ function listInterestGroupUpdate($id, $old_name, $new_name) {
1012
+ $params = array();
1013
+ $params["id"] = $id;
1014
+ $params["old_name"] = $old_name;
1015
+ $params["new_name"] = $new_name;
1016
+ return $this->callServer("listInterestGroupUpdate", $params);
1017
+ }
1018
+
1019
+ /** Return the Webhooks configured for the given list
1020
+ *
1021
+ * @section List Related
1022
+ *
1023
+ * @param string $id the list id to connect to. Get by calling lists()
1024
+ * @return array list of webhooks
1025
+ * @returnf string url the URL for this Webhook
1026
+ * @returnf array actions the possible actions and whether they are enabled
1027
+ * @returnf array sources the possible sources and whether they are enabled
1028
+ */
1029
+ function listWebhooks($id) {
1030
+ $params = array();
1031
+ $params["id"] = $id;
1032
+ return $this->callServer("listWebhooks", $params);
1033
+ }
1034
+
1035
+ /** Add a new Webhook URL for the given list
1036
+ *
1037
+ * @section List Related
1038
+ *
1039
+ * @param string $id the list id to connect to. Get by calling lists()
1040
+ * @param string $url a valid URL for the Webhook - it will be validated. note that a url may only exist on a list once.
1041
+ * @param array $actions optional a hash of actions to fire this Webhook for
1042
+ boolean subscribe optional as subscribes occur, defaults to true
1043
+ boolean unsubscribe optional as subscribes occur, defaults to true
1044
+ boolean profile optional as profile updates occur, defaults to true
1045
+ boolean cleaned optional as emails are cleaned from the list, defaults to true
1046
+ boolean upemail optional when subscribers change their email address, defaults to true
1047
+ * @param array $sources optional a hash of sources to fire this Webhook for
1048
+ boolean user optional user/subscriber initiated actions, defaults to true
1049
+ boolean admin optional admin actions in our web app, defaults to true
1050
+ boolean api optional actions that happen via API calls, defaults to false
1051
+ * @return bool true if the call succeeds, otherwise an exception will be thrown
1052
+ */
1053
+ function listWebhookAdd($id, $url, $actions=array (
1054
+ ), $sources=array (
1055
+ )) {
1056
+ $params = array();
1057
+ $params["id"] = $id;
1058
+ $params["url"] = $url;
1059
+ $params["actions"] = $actions;
1060
+ $params["sources"] = $sources;
1061
+ return $this->callServer("listWebhookAdd", $params);
1062
+ }
1063
+
1064
+ /** Delete an existing Webhook URL from a given list
1065
+ *
1066
+ * @section List Related
1067
+ *
1068
+ * @param string $id the list id to connect to. Get by calling lists()
1069
+ * @param string $url the URL of a Webhook on this list
1070
+ * @return boolean true if the call succeeds, otherwise an exception will be thrown
1071
+ */
1072
+ function listWebhookDel($id, $url) {
1073
+ $params = array();
1074
+ $params["id"] = $id;
1075
+ $params["url"] = $url;
1076
+ return $this->callServer("listWebhookDel", $params);
1077
+ }
1078
+
1079
  /**
1080
+ * 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!
1081
  *
1082
  * @section List Related
1083
  *
1084
  * @example mcapi_listSubscribe.php
1085
  * @example xml-rpc_listSubscribe.php
1086
  *
1087
+ * @param string $id the list id to connect to. Get by calling lists()
1088
  * @param string $email_address the email address to subscribe
1089
+ * @param array $merge_vars array of 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 characters. Also, there are 2 "special" keys:
1090
+ string INTERESTS Set Interest Groups by passing a field named "INTERESTS" that contains a comma delimited list of Interest Groups to add. Commas in Interest Group names should be escaped with a backslash. ie, "," =&gt; "\,"
1091
+ 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.
1092
+
1093
+ <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...
1094
+ Field values should be formatted as follows:
1095
+ 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
1096
+ 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
1097
+
1098
+ 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>
1099
+ string dropdown can be a normal string - we <em>will</em> validate that the value is a valid option
1100
+ string image must be a valid, existing url. we <em>will</em> check its existence
1101
+ string multi_choice can be a normal string - we <em>will</em> validate that the value is a valid option
1102
+ double number pass in a valid number - anything else will turn in to zero (0). Note, this will be rounded to 2 decimal places
1103
+ 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.
1104
+ string website This is a standard string, but we <em>will</em> verify that it looks like a valid URL
1105
+
1106
+
1107
+
1108
  * @param string $email_type optional - email type preference for the email (html or text, defaults to html)
1109
+ * @param boolean $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>
1110
+ * @param boolean $update_existing optional - flag to control whether a existing subscribers should be updated instead of throwing and error
1111
+ * @param boolean $replace_interests - 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)
1112
+ * @param boolean $send_welcome - 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. defaults to false
1113
+
1114
  * @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)
1115
  */
1116
+ function listSubscribe($id, $email_address, $merge_vars, $email_type='html', $double_optin=true, $update_existing=false, $replace_interests=true, $send_welcome=false) {
1117
  $params = array();
1118
  $params["id"] = $id;
1119
  $params["email_address"] = $email_address;
1120
  $params["merge_vars"] = $merge_vars;
1121
  $params["email_type"] = $email_type;
1122
  $params["double_optin"] = $double_optin;
1123
+ $params["update_existing"] = $update_existing;
1124
+ $params["replace_interests"] = $replace_interests;
1125
+ $params["send_welcome"] = $send_welcome;
1126
  return $this->callServer("listSubscribe", $params);
1127
  }
1128
 
1131
  *
1132
  * @section List Related
1133
  * @example mcapi_listUnsubscribe.php
1134
+ * @example xml-rpc_listUnsubscribe.php
1135
  *
1136
+ * @param string $id the list id to connect to. Get by calling lists()
1137
  * @param string $email_address the email address to unsubscribe
1138
  * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
1139
  * @param boolean $send_goodbye flag to send the goodbye email to the email address, defaults to true
1154
  * Edit the email address, merge fields, and interest groups for a list member
1155
  *
1156
  * @section List Related
1157
+ * @example mcapi_listUpdateMember.php
1158
  *
1159
+ * @param string $id the list id to connect to. Get by calling lists()
1160
  * @param string $email_address the current email address of the member to update
1161
  * @param array $merge_vars array of new field values to update the member with. Use "EMAIL" to update the email address and "INTERESTS" to update the interest groups
1162
  * @param string $email_type change the email type preference for the member ("html" or "text"). Leave blank to keep the existing preference (optional)
1177
  * Subscribe a batch of email addresses to a list at once
1178
  *
1179
  * @section List Related
1180
+ *
1181
+ * @example mcapi_listBatchSubscribe.php
1182
  * @example xml-rpc_listBatchSubscribe.php
1183
  *
1184
+ * @param string $id the list id to connect to. Get by calling lists()
1185
  * @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 or text)
1186
  * @param boolean $double_optin flag to control whether to send an opt-in confirmation email - defaults to true
1187
  * @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)
1189
  * @return struct Array of result counts and any errors that occurred
1190
  * @returnf integer success_count Number of email addresses that were succesfully added/updated
1191
  * @returnf integer error_count Number of email addresses that failed during addition/updating
1192
+ * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and the full struct that failed
1193
  */
1194
  function listBatchSubscribe($id, $batch, $double_optin=true, $update_existing=false, $replace_interests=true) {
1195
  $params = array();
1205
  * Unsubscribe a batch of email addresses to a list
1206
  *
1207
  * @section List Related
1208
+ * @example mcapi_listBatchUnsubscribe.php
1209
  *
1210
+ * @param string $id the list id to connect to. Get by calling lists()
1211
  * @param array $emails array of email addresses to unsubscribe
1212
  * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
1213
  * @param boolean $send_goodbye flag to send the goodbye email to the email addresses, defaults to true
1215
  * @return struct Array of result counts and any errors that occurred
1216
  * @returnf integer success_count Number of email addresses that were succesfully added/updated
1217
  * @returnf integer error_count Number of email addresses that failed during addition/updating
1218
+ * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and "email"
1219
  */
1220
  function listBatchUnsubscribe($id, $emails, $delete_member=false, $send_goodbye=true, $send_notify=false) {
1221
  $params = array();
1228
  }
1229
 
1230
  /**
1231
+ * Get all of the list members for a list that are of a particular status
1232
  *
1233
  * @section List Related
1234
  * @example mcapi_listMembers.php
1235
  *
1236
+ * @param string $id the list id to connect to. Get by calling lists()
1237
+ * @param string $status the status to get members for - one of(subscribed, unsubscribed, cleaned, updated), defaults to subscribed
1238
+ * @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)
1239
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1240
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 15000
1241
  * @return array Array of list member structs (see Returned Fields for details)
1242
  * @returnf string email Member email address
1243
+ * @returnf date timestamp timestamp of their associated status date (subscribed, unsubscribed, cleaned, or updated) in GMT
1244
  */
1245
+ function listMembers($id, $status='subscribed', $since=NULL, $start=0, $limit=100) {
1246
  $params = array();
1247
  $params["id"] = $id;
1248
  $params["status"] = $status;
1249
+ $params["since"] = $since;
1250
  $params["start"] = $start;
1251
  $params["limit"] = $limit;
1252
  return $this->callServer("listMembers", $params);
1257
  *
1258
  * @section List Related
1259
  * @example mcapi_listMemberInfo.php
1260
+ * @example xml-rpc_listMemberInfo.php
1261
+ *
1262
+ * @param string $id the list id to connect to. Get by calling lists()
1263
  * @param string $email_address the member email address to get information for
1264
  * @return array array of list member info (see Returned Fields for details)
1265
  * @returnf string email The email address associated with this record
1266
  * @returnf string email_type The type of emails this customer asked to get: html or text
1267
+ * @returnf 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, "," =&gt; "\,"
1268
  * @returnf string status The subscription status for this email address, either subscribed, unsubscribed or cleaned
1269
+ * @returnf string ip_opt IP Address this address opted in from.
1270
+ * @returnf string ip_signup IP Address this address signed up from.
1271
+ * @returnf 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.
1272
  * @returnf date timestamp The time this email address was added to the list
1273
  */
1274
  function listMemberInfo($id, $email_address) {
1278
  return $this->callServer("listMemberInfo", $params);
1279
  }
1280
 
1281
+ /**
1282
+ * Get all email addresses that complained about a given campaign
1283
+ *
1284
+ * @section List Related
1285
+ *
1286
+ * @example mcapi_listAbuseReports.php
1287
+ *
1288
+ * @param string $id the list id to pull abuse reports for (can be gathered using lists())
1289
+ * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1290
+ * @param integer $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
1291
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
1292
+ * @return array reports the abuse reports for this campaign
1293
+ * @returnf string date date/time the abuse report was received and processed
1294
+ * @returnf string email the email address that reported abuse
1295
+ * @returnf string campaign_id the unique id for the campaign that reporte was made against
1296
+ * @returnf string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
1297
+ */
1298
+ function listAbuseReports($id, $start=0, $limit=500, $since=NULL) {
1299
+ $params = array();
1300
+ $params["id"] = $id;
1301
+ $params["start"] = $start;
1302
+ $params["limit"] = $limit;
1303
+ $params["since"] = $since;
1304
+ return $this->callServer("listAbuseReports", $params);
1305
+ }
1306
+
1307
+ /**
1308
+ * Access the Growth History by Month for a given list.
1309
+ *
1310
+ * @section List Related
1311
+ *
1312
+ * @example mcapi_listGrowthHistory.php
1313
+ *
1314
+ * @param string $id the list id to connect to. Get by calling lists()
1315
+ * @return array array of months and growth
1316
+ * @returnf string month The Year and Month in question using YYYY-MM format
1317
+ * @returnf integer existing number of existing subscribers to start the month
1318
+ * @returnf integer import number of subscribers imported during the month
1319
+ * @returnf integer optins number of subscribers who opted-in during the month
1320
+ */
1321
+ function listGrowthHistory($id) {
1322
+ $params = array();
1323
+ $params["id"] = $id;
1324
+ return $this->callServer("listGrowthHistory", $params);
1325
+ }
1326
+
1327
+ /**
1328
+ * <strong>DEPRECATED:</strong> Retrieve your User Unique Id and your Affiliate link to display/use for
1329
+ * <a href="/monkeyrewards/" target="_blank">Monkey Rewards</a>. While
1330
+ * we don't use the User Id for any API functions, it can be useful if building up URL strings for things such as the profile editor and sub/unsub links.
1331
+ *
1332
+ * @section Helper
1333
+ *
1334
+ * @deprecated See getAccountDetails() for replacement
1335
+ *
1336
+ * @example mcapi_getAffiliateInfo.php
1337
+ * @example xml-rpc_getAffiliateInfo.php
1338
+ *
1339
+ * @return array containing your Affilliate Id and full link.
1340
+ * @returnf string user_id Your User Unique Id.
1341
+ * @returnf string url Your Monkey Rewards link for our Affiliate program
1342
+ */
1343
+ function getAffiliateInfo() {
1344
+ $params = array();
1345
+ return $this->callServer("getAffiliateInfo", $params);
1346
+ }
1347
+
1348
+ /**
1349
+ * Retrieve lots of account information including payments made, plan info, some account stats, installed modules,
1350
+ * contact info, and more. No private information like Credit Card numbers is available.
1351
+ *
1352
+ * @section Helper
1353
+ *
1354
+ * @return array containing the details for the account tied to this API Key
1355
+ * @returnf string username The Account username
1356
+ * @returnf string user_id The Account user unique id (for building some links)
1357
+ * @returnf bool is_trial Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
1358
+ * @returnf string timezone The timezone for the Account - default is "US/Eastern"
1359
+ * @returnf string plan_type Plan Type - "monthly", "payasyougo", or "free"
1360
+ * @returnf int plan_low <em>only for Monthly plans</em> - the lower tier for list size
1361
+ * @returnf int plan_high <em>only for Monthly plans</em> - the upper tier for list size
1362
+ * @returnf datetime plan_start_date <em>only for Monthly plans</em> - the start date for a monthly plan
1363
+ * @returnf int emails_left <em>only for Free and Pay-as-you-go plans</em> emails credits left for the account
1364
+ * @returnf bool pending_monthly Whether the account is finishing Pay As You Go credits before switching to a Monthly plan
1365
+ * @returnf datetime first_payment date of first payment
1366
+ * @returnf datetime last_payment date of most recent payment
1367
+ * @returnf int times_logged_in total number of times the account has been logged into via the web
1368
+ * @returnf datetime last_login date/time of last login via the web
1369
+ * @returnf string affiliate_link Monkey Rewards link for our Affiliate program
1370
+ * @returnf array contact Contact details for the account, including: First & Last name, email, company name, address, phone, and url
1371
+ * @returnf array addons Addons installed in the account and the date they were installed.
1372
+ * @returnf array orders Order details for the account, include order_id, type, cost, date/time, and any credits applied to the order
1373
+ */
1374
+ function getAccountDetails() {
1375
+ $params = array();
1376
+ return $this->callServer("getAccountDetails", $params);
1377
+ }
1378
+
1379
+ /**
1380
+ * 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.
1381
+ *
1382
+ * @section Helper
1383
+ * @example xml-rpc_generateText.php
1384
+ *
1385
+ * @param string $type The type of content to parse. Must be one of: "html", "template", "url", "cid" (Campaign Id), or "tid" (Template Id)
1386
+ * @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.
1387
+ * @return string the content pass in converted to text.
1388
+ */
1389
+ function generateText($type, $content) {
1390
+ $params = array();
1391
+ $params["type"] = $type;
1392
+ $params["content"] = $content;
1393
+ return $this->callServer("generateText", $params);
1394
+ }
1395
+
1396
+ /**
1397
+ * Send your HTML content to have the CSS inlined and optionally remove the original styles.
1398
+ *
1399
+ * @section Helper
1400
+ * @example xml-rpc_inlineCss.php
1401
+ *
1402
+ * @param string $html Your HTML content
1403
+ * @param bool $strip_css optional Whether you want the CSS &lt;style&gt; tags stripped from the returned document. Defaults to false.
1404
+ * @return string Your HTML content with all CSS inlined, just like if we sent it.
1405
+ */
1406
+ function inlineCss($html, $strip_css=false) {
1407
+ $params = array();
1408
+ $params["html"] = $html;
1409
+ $params["strip_css"] = $strip_css;
1410
+ return $this->callServer("inlineCss", $params);
1411
+ }
1412
+
1413
+ /**
1414
+ * Create a new folder to file campaigns in
1415
+ *
1416
+ * @section Helper
1417
+ * @example mcapi_createFolder.php
1418
+ * @example xml-rpc_createFolder.php
1419
+ *
1420
+ * @param string $name a unique name for a folder
1421
+ * @return integer the folder_id of the newly created folder.
1422
+ */
1423
+ function createFolder($name) {
1424
+ $params = array();
1425
+ $params["name"] = $name;
1426
+ return $this->callServer("createFolder", $params);
1427
+ }
1428
+
1429
+ /**
1430
+ * Retrieve a list of all MailChimp API Keys for this User
1431
+ *
1432
+ * @section Security Related
1433
+ * @example xml-rpc_apikeyAdd.php
1434
+ * @example mcapi_apikeyAdd.php
1435
+ *
1436
+ * @param string $username Your MailChimp user name
1437
+ * @param string $password Your MailChimp password
1438
+ * @param boolean $expired optional - whether or not to include expired keys, defaults to false
1439
+ * @return array an array of API keys including:
1440
+ * @returnf string apikey The api key that can be used
1441
+ * @returnf string created_at The date the key was created
1442
+ * @returnf string expired_at The date the key was expired
1443
+ */
1444
+ function apikeys($username, $password, $expired=false) {
1445
+ $params = array();
1446
+ $params["username"] = $username;
1447
+ $params["password"] = $password;
1448
+ $params["expired"] = $expired;
1449
+ return $this->callServer("apikeys", $params);
1450
+ }
1451
+
1452
+ /**
1453
+ * Add an API Key to your account. We will generate a new key for you and return it.
1454
+ *
1455
+ * @section Security Related
1456
+ * @example xml-rpc_apikeyAdd.php
1457
+ *
1458
+ * @param string $username Your MailChimp user name
1459
+ * @param string $password Your MailChimp password
1460
+ * @return string a new API Key that can be immediately used.
1461
+ */
1462
+ function apikeyAdd($username, $password) {
1463
+ $params = array();
1464
+ $params["username"] = $username;
1465
+ $params["password"] = $password;
1466
+ return $this->callServer("apikeyAdd", $params);
1467
+ }
1468
+
1469
+ /**
1470
+ * Expire a Specific API Key. Note that if you expire all of your keys, a new, valid one will be created and returned
1471
+ * next time you call login(). If you are trying to shut off access to your account for an old developer, change your
1472
+ * MailChimp password, then expire all of the keys they had access to. Note that this takes effect immediately, so make
1473
+ * sure you replace the keys in any working application before expiring them! Consider yourself warned...
1474
+ *
1475
+ * @section Security Related
1476
+ * @example mcapi_apikeyExpire.php
1477
+ * @example xml-rpc_apikeyExpire.php
1478
+ *
1479
+ * @param string $username Your MailChimp user name
1480
+ * @param string $password Your MailChimp password
1481
+ * @return boolean true if it worked, otherwise an error is thrown.
1482
+ */
1483
+ function apikeyExpire($username, $password) {
1484
+ $params = array();
1485
+