s2Member Framework (Member Roles, Capabilities, Membership, PayPal Members) - Version 110604

Version Description

( instead of s2Member v3.6 ) = * (s2Member/s2Member Pro). Versioning. Starting with this release, s2Member and s2Member Pro will be released with dated versions following this format: yymmdd. The version for this release is: 110604. * (s2Member/s2Member Pro). s2Member Security Badge. An s2Member Security Badge ( optional ), can be used to express your site's concern for security; demonstrating to all Users/Members that your site ( and the s2Member software ), takes security seriously. However, in order to qualify your site, you MUST generate a Security Encryption Key and pass other security standards. For more information, please check your Dashboard under: s2Member -> General Options -> Security Badge. * (s2Member/s2Member Pro). Custom Fields For BuddyPress. s2Member can now integrate your Custom Fields into BuddyPress. Please check your Dashboard for all configuration options. You'll find BuddyPress integration available here: DashBoard -> s2Member -> General Options -> Custom Registration Fields. * (s2Member Pro). PayPal Pro API Updates (First Payment / Recurring Profile Behavior). s2Member's integration with the PayPal Pro API has been updated to API v71.0. There is also a new option available to PayPal Pro Merchants. s2Member now provides site owners the abililty to control the way the first payment in a Recurring Profile is billed. (1)Consolidate w/ Recurring Profile or (2) Real-Time / Direct Pay ( mission critical ) . For further details, please check your Dashboard under: s2Member -> PayPal Options -> Account Details. We recommend: Consolidate w/ Recurring Profile, because this keeps all charges associated with a particular Customer organized in your PayPal account. No matter which option you choose, a first Initial Payment ( when applicable ), will always be charged immediately ( improved in this release ). In cases where it is absolutely critical that a Customer NOT gain access until their first payment has been fully captured, choose: Real-Time / Direct Pay, which tells s2Member to authorize/capture the first payment in real-time during checkout, instead of consolidating it into the Recurring Profile. * (s2Member). bbPress 2.0+. s2Member has been integrated with preliminary support for bbPress 2.0+ ( i.e. the new plugin variation for WordPress ). Please check your Dashboard, under: s2Member -> Other Integrations for further details and a list of current limitations. * (s2Member/s2Member Pro). Field Labels. Some additional for="" attributes in all Pro Form templates. This improves the reliability of s2Member's JavaScript validation routines. Existing s2Member Pro Customers with modified Pro Form templates MUST update their for="" attributes in order for s2Member's JavaScript API to properly validate Customer data entry in this new release. If you're running custom Pro Form templates, check this directory for the updated default templates, so you can merge any changes you've made yourself: /s2member-pro/includes/templates/forms/. * (s2Member). Amazon S3 Support Amazon Simple Storage Service ( Amazon S3 ). Amazon S3 is storage for the Internet. It is designed to make web-scale computing easier for developers. Amazon S3 provides a simple web services interface that can be used to store and retrieve any amount of data, at any time, from anywhere on the web. It gives developers access to the same highly scalable, reliable, secure, fast, inexpensive infrastructure that Amazon uses to run its own global network of web sites. s2Member has been integrated with Amazon S3, so that ( if you wish ), instead of using the /s2member-files/ directory, you can store all of your protected files inside an Amazon S3 Bucket. * (s2Member/s2Member Pro). jQuery. Tested s2Member against jQuery version 1.4.4+, including jQuery v1.6. Fixed a bug with .attr() returning undefined in jQuery v1.6. * (s2Member). Bug fix. Using the Replacement Code %%current_user_login%% in a Special Redirection URL for your Login Welcome Page would sometimes result in your Home Page being protected inadvertently, depending on configuration. * (s2Member/s2Member Pro). IP Address Collection. s2Member now records the original IP Address of a each User, for tracking purposes. In previous versions of s2Member, in order to integrate some tracking systems, ( such as iDevAffiliate's server-side call option ), it was required to use the custom="" Attribute of your Shortcode to grab a Customer's IP Address. That's no longer required, as Replacement Codes are now made available throughout all aspects of s2Member; giving you easy access to the User's IP Address. * (s2Member Pro). Bug fix. Buy Now Coupon descriptions for Specific Post/Page Access were returning invalid details, referencing installments. This bug has been resolved. * (s2Member Pro). SSL. Allow ?s2-ssl without a value ( accept as true ). This has been implemented for advanced site owners running s2Member Pro Forms. * (s2Member/s2Member Pro). API Functions. New API functions for user Level, Role, Custom Capabilities. These will be documented in our official source code documentation system for s2Member ( also new ). Source code documentation will become available in the s2Member forums, shortly after the official public release of this version. * (s2Member/s2Member Pro). New Shortcode Attribute. For PayPal Buttons/Forms, you can now apply Shortcode lc="US". Optional 2 character Locale Code ( i.e. Country Code ). This controls the interface language used if/when a Customer chooses PayPal Express Checkout as their payment method, or upon clicking a Standard PayPal Button. If unspecified, the language is determined by PayPal, when possible, defaulting to US english when not possible. * (s2Member/s2Member Pro). New Shortcode Attribute. For PayPal Buttons/Forms, you can now apply Shortcode rrt="". Regular Recurring Times ( i.e. a fixed number of installments ). Only valid w/ Membership Level Access. When unspecified ( the default ), any recurring charges will remain ongoing until cancelled, or until payments start failing. If this is set to 1 or higher the regular recurring charges will only continue for X billing cycles, depending on what you specify. This is only valid when rr="1" for recurring "Subscriptions". Please note that a fixed number of installments, also means a fixed period of access. If a Customer's billing is monthly, and you set rrt="3", billing will continue for only 3 monthly installments. After that, billing would stop, and their access to the site would be revoked as well ( based on your EOT Behavior setting under: s2Member -> PayPal Options ). * (s2Member/s2Member Pro). New Shortcode Attribute. You can now apply rra="1". This has to do with reattempting failed payments. It has slightly different meanings and option values, depending on whether it's used for a PayPal Button or a PayPal Pro Form Shortcode. For instance, for PayPal Pro Form Shortcodes, this also controls MAXFAILEDPAYMENTS. Please check your Dashboard under: s2Member -> PayPal Buttons/Forms -> Shortcode Attributes Explained. * (s2Member w/s2Member Pro installed). New Shortcode Attribute. You can now apply success="http://..." Attribute to Standard PayPal Buttons. Success Return URL ( optional ). s2Member handles this automatically for you. However, if you would prefer to take control over the landing page after checkout ( i.e. your own custom Thank-You Page ), you can. If supplied, this must be a full URL, starting with http://. Note, s2Member will NOT use this value if an existing account holder is being modified. s2Member handles account updates ( i.e. billing modification ) in a more dynamic way. Your Success Return URL is only applied to (new) Customers. This feature is enabled with s2Member Pro installed. * (s2Member/s2Member Pro). Bug fix. When using ampersands in the success="" Attribute, it would break Success Return URLs on some WordPress installations. s2Member now converts these internally to avoid the issue. * (s2Member). Redirection Status Codes. s2Member's default behavior ( for good reason ), is to send a 301 redirection status when it moves unauthorized Visitors to your Membership Options Page. The reasons for this are well founded. This prevents duplicate content warnings from search engine spiders. However, some web browsers ( like Safari ) make an attempt to cache a 301 redirection into memory, thereby preventing some browsers from reaching the proper areas of your site after logging in, had they been redirected to the Membership Options Page prior. s2Member resolves this problem by detecting all major browser engines ( i.e. msie|trident|gecko|webkit|presto|konqueror|playstation ) and sending web browsers a 302 redirection, while still sending spiders/crawlers ( such as the Google bot ), the proper 301 redirection status. For further details, please check this thread. * (s2Member). Alternative Views. Alternative View Restrictions ( now compatible with Ajax search plugins ). For further details, please check this thread. * (s2Member Pro). Bug fix. Corrected first/last name updates during Pro Form checkout/upgrade routines. s2Member Pro should use ( and update to ) the values submitted, even when already logged-in. * (s2Member/s2Member Pro). Bug fix. s2Member was not properly filling the $_GET["s2member_level_req"] parameter upon certain File Download Restrictions. For instance, s2Member would sometimes return s2member_level_req=0, even though you protected a File inside a Custom Capability and/or Member Level sub-directory. This bug has been corrected. * (s2Member/s2Member Pro). Time Zone. s2Member now displays Registration Dates in your list of Users with date_i18n() for localized time, as opposed to UTC time. UTC time is still the default time zone ( internally ), this is built into the WordPress core. However, certain dates displayed on-site are easier to understand in localized time, based on your WordPress General Settings. * (s2Member). Password Confirmation. s2Member now provides a Password confirmation field on the Standard Registration Form, and in other key areas, such as Profile Editing Panels. * (s2Member/s2Member Pro). Password Strength Meters. This version adds Password strength meters in various places ( where it's helpful ); including s2Member Pro Forms, and even the default Registration Form for WordPress. * (s2Member). Multisite Registration. Cleaned up the default Multisite Registration Form ( i.e. /wp-signup.php ), with structural CSS to better support s2Member features. * (s2Member/s2Member Pro). SI Captchya. s2Member now contains default CSS styles ( just two lines ), and JavaScript validation for the popular SI Capchya plugin; and also for it's own built-in support of Google's reCAPTCHA service for s2Member Pro Forms. * (s2Member/s2Member Pro). Custom Field Default Values. It's now possible to set default text values for single-line and multi-line input/textarea fields too. This only affects Custom Fields you configure with s2Member. * (s2Member/s2Member Pro). Custom Fields By Section. Custom Fields by section ( i.e. dividers ). It's now possible to configure certain Custom Fields, so that they start a new section. Your sections can be simple dividing lines, or you can give them a title that will appear on your Registration and Profile Editing forms. * (s2Member). Bug fix. s2Member was creating window focus/blur issues on Profile updates through its Stand-Alone version of the Profile Editing Panel ( i.e. when it was popped open in a new window ). This was causing odd behavior Firefox 4. * (s2Member/s2Member Pro). Remove First/Last Name. It is now possible to turn off First/Last/Display Name, on Registration and Profile Editing forms. For configuration options, please check your Dashboard, under: s2Member -> Custom Registration Fields. * (s2Member Pro). Data Prefill. s2Member Pro is now capable of prepopulating some Pro Form fields when/if existing Users buy a Specific Post/Page. * (s2Member/s2Member Pro). Bug fix. Fixed nested Custom Registration Field labels for multi option check boxes/radios. Firefox 4+ had issues with this. * (s2Member/s2Member Pro). Registration Link Expiration. The default is built-in, it's (2) days. We don't recommend changing this unless you know what you're doing. Some developers requested the ability to change this dynamically. s2Member now makes this Filter available: ws_plugin__s2member_register_link_exp_time. * (s2Member Pro). Automatic Upgrade Routine. s2Member Pro now places your site into maintenance mode ( temporarily ) during an s2Member Pro Upgrade routine. * (s2Member). New API Notification. New "Modification" Notification now available under: s2Member -> API Notifications. Say that three times fast! * (s2Member/s2Member Pro). MailChimp / AWeber improvements. This release fixes several bugs related to Automatic Unsubscribes, general list removals, and introduces a new feature call Automatic List Transitions. For further details, please check your Dashboard under: s2Member -> API List Servers. * (s2Member). Bug fix. PayPal Button Codes should have been including a charset input variable for UTF-8 encoding. This bug has been corrected now. If you've had trouble getting special characters to appear properly in the PayPal interface, this version should correct those issues for you. * (s2Member/s2Member Pro). Animated Processing... Buttons. This release adds simple animated "processing..." messages to all form submission buttons. * (s2Member/s2Member Pro). MailChimp Interest Groups. Ability to use Interest Groups with Mailchimp List IDs. For examples, please check your Dashboard under: s2Member -> API List Servers -> MailChimp. * (s2Member/s2Member Pro). New EOT Behavior Option. Automatic Extension of EOT Time whenever a Customer is upgrading a paid Subscription? For configuration options, please check your Dashboard under: s2Member -> PayPal Options -> EOT Behavior. * (s2Member/s2Member Pro). Log Entries. WordPress :: s2Member :: s2Member Pro versions now all reported in each log entry. In addition, s2Member now provides logging for all communications with MailChimp and AWeber too. * (s2Member/s2Member Pro). s2Member Now Requires WordPress v3.1+. Backward compatibility for the WordPress 3.0.x series has been removed. Also removed all include() references to /wp-includes/registration.php. Deprecated in WordPress v3.1. This file no longer needs to be included. * (s2Member/s2Member Pro). s2Member Updates. New built-in news updates from s2Member developers. This appears in your Dashboard automatically, inside the s2Member menu panels. * (s2Member/s2Member Pro). Bug fix. Custom Post Types were not appearing in s2Member's Specific Post/Page Button and Form Generators, even when configured properly. This bug has been resolved. * (s2Member/s2Member Pro). Documentation. Built-in documentation updated throughout. * (s2Member/s2Member Pro). UI Panels. Some minor UI improvements.

Download this release

Release Info

Developer PriMoThemes
Plugin Icon 128x128 s2Member Framework (Member Roles, Capabilities, Membership, PayPal Members)
Version 110604
Comparing to
See all releases

Code changes from version 3.5.8 to 110604

Files changed (179) hide show
  1. images/amazon-logo.png +0 -0
  2. images/brand-donations.fla +0 -0
  3. images/brand-donations.jpg +0 -0
  4. images/brand-donations.png +0 -0
  5. images/logo.fla +0 -0
  6. images/logo.png +0 -0
  7. images/s2-powered.png +0 -0
  8. includes/{mailchimp → _xtnls}/index.php +0 -0
  9. includes/{markdown → _xtnls/mailchimp}/index.php +0 -0
  10. includes/_xtnls/mailchimp/nc-mcapi.inc.php +2515 -0
  11. includes/_xtnls/markdown/index.php +0 -0
  12. includes/{markdown → _xtnls/markdown}/nc-markdown.inc.php +30 -24
  13. includes/classes/admin-css-js-in.inc.php +56 -31
  14. includes/classes/admin-css-js.inc.php +40 -19
  15. includes/classes/admin-lockouts.inc.php +46 -22
  16. includes/classes/admin-notices.inc.php +75 -41
  17. includes/classes/auto-eots.inc.php +99 -69
  18. includes/classes/brute-force.inc.php +52 -24
  19. includes/classes/cache.inc.php +33 -16
  20. includes/classes/catgs-sp.inc.php +47 -46
  21. includes/classes/catgs.inc.php +43 -42
  22. includes/classes/check-activation.inc.php +33 -26
  23. includes/classes/constants.inc.php +2219 -101
  24. includes/classes/cron-jobs-in.inc.php +40 -18
  25. includes/classes/cron-jobs.inc.php +40 -18
  26. includes/classes/css-js-in.inc.php +70 -35
  27. includes/classes/css-js-themes.inc.php +43 -20
  28. includes/classes/css-js.inc.php +41 -20
  29. includes/classes/custom-reg-fields-4bp.inc.php +280 -0
  30. includes/classes/custom-reg-fields.inc.php +346 -227
  31. includes/classes/email-configs.inc.php +78 -27
  32. includes/classes/files-checks.inc.php +0 -34
  33. includes/classes/files-in.inc.php +151 -76
  34. includes/classes/files.inc.php +136 -107
  35. includes/classes/installation.inc.php +54 -163
  36. includes/classes/ip-restrictions.inc.php +152 -96
  37. includes/classes/labels.inc.php +42 -18
  38. includes/classes/list-servers.inc.php +263 -78
  39. includes/classes/login-customizations.inc.php +97 -58
  40. includes/classes/login-redirects-r.inc.php +33 -16
  41. includes/classes/login-redirects.inc.php +110 -55
  42. includes/classes/menu-pages-rs.inc.php +97 -0
  43. includes/classes/menu-pages.inc.php +276 -155
  44. includes/classes/meta-box-saves.inc.php +32 -17
  45. includes/classes/meta-box-security.inc.php +41 -26
  46. includes/classes/meta-boxes.inc.php +38 -18
  47. includes/classes/mms-patches.inc.php +47 -25
  48. includes/classes/mo-page-in.inc.php +34 -21
  49. includes/classes/mo-page.inc.php +35 -22
  50. includes/classes/no-cache.inc.php +171 -0
  51. includes/classes/nocache.inc.php +0 -124
  52. includes/classes/op-notices.inc.php +55 -40
  53. includes/classes/option-forces.inc.php +109 -45
  54. includes/classes/pages-sp.inc.php +52 -51
  55. includes/classes/pages.inc.php +52 -50
  56. includes/classes/paypal-notify-in.inc.php +664 -325
  57. includes/classes/paypal-notify.inc.php +30 -25
  58. includes/classes/paypal-return-in.inc.php +100 -57
  59. includes/classes/paypal-return.inc.php +30 -15
  60. includes/classes/paypal-utilities.inc.php +188 -101
  61. includes/classes/posts-sp.inc.php +55 -54
  62. includes/classes/posts.inc.php +55 -53
  63. includes/classes/profile-in.inc.php +277 -18
  64. includes/classes/profile-mods-4bp-in.inc.php +112 -0
  65. includes/classes/profile-mods-4bp.inc.php +49 -0
  66. includes/classes/profile-mods-in.inc.php +79 -44
  67. includes/classes/profile-mods.inc.php +31 -16
  68. includes/classes/profile.inc.php +31 -16
  69. includes/classes/ptags-sp.inc.php +52 -51
  70. includes/classes/ptags.inc.php +40 -38
  71. includes/classes/querys.inc.php +182 -174
  72. includes/classes/readmes.inc.php +58 -24
  73. includes/classes/register-access.inc.php +43 -18
  74. includes/classes/register-in.inc.php +33 -18
  75. includes/classes/register.inc.php +31 -16
  76. includes/classes/registration-times.inc.php +50 -35
  77. includes/classes/registrations.inc.php +347 -208
  78. includes/classes/roles-caps.inc.php +152 -0
  79. includes/classes/ruris-sp.inc.php +42 -42
  80. includes/classes/ruris.inc.php +54 -43
  81. includes/classes/s-badge-status-in.inc.php +89 -0
  82. includes/classes/s-badge-status.inc.php +49 -0
  83. includes/classes/sc-gets-in.inc.php +40 -25
  84. includes/classes/sc-gets.inc.php +32 -18
  85. includes/classes/sc-if-conds-in.inc.php +51 -29
  86. includes/classes/sc-if-conds.inc.php +42 -24
  87. includes/classes/sc-paypal-button-e.inc.php +37 -20
  88. includes/classes/sc-paypal-button-in.inc.php +87 -31
  89. includes/classes/sc-paypal-button.inc.php +32 -14
  90. includes/classes/sc-profile-in.inc.php +137 -109
  91. includes/classes/sc-profile.inc.php +32 -14
  92. includes/classes/sc-s-badge-in.inc.php +58 -0
  93. includes/classes/sc-s-badge.inc.php +49 -0
  94. includes/classes/security.inc.php +40 -22
  95. includes/classes/sp-access.inc.php +74 -31
  96. includes/classes/ssl-in.inc.php +40 -31
  97. includes/classes/ssl.inc.php +38 -26
  98. includes/classes/systematics-sp.inc.php +39 -22
  99. includes/classes/systematics.inc.php +33 -21
  100. includes/classes/tracking-codes.inc.php +67 -42
  101. includes/classes/tracking-cookies-in.inc.php +40 -19
  102. includes/classes/tracking-cookies.inc.php +41 -20
  103. includes/classes/translations.inc.php +70 -67
  104. includes/classes/user-access.inc.php +115 -38
  105. includes/classes/user-deletions.inc.php +89 -58
  106. includes/classes/user-new-in.inc.php +111 -79
  107. includes/classes/user-new.inc.php +33 -17
  108. includes/classes/user-notes.inc.php +40 -17
  109. includes/classes/user-securities.inc.php +78 -34
  110. includes/classes/users-list-in.inc.php +221 -127
  111. includes/classes/users-list.inc.php +93 -96
  112. includes/classes/utilities.inc.php +84 -17
  113. includes/classes/utils-arrays.inc.php +46 -18
  114. includes/classes/utils-captchas.inc.php +40 -16
  115. includes/classes/utils-conds.inc.php +64 -48
  116. includes/classes/utils-css.inc.php +40 -15
  117. includes/classes/utils-cur.inc.php +107 -0
  118. includes/classes/utils-dirs.inc.php +38 -16
  119. includes/classes/utils-encryption.inc.php +68 -21
  120. includes/classes/utils-forms.inc.php +36 -15
  121. includes/classes/utils-gets.inc.php +88 -35
  122. includes/classes/utils-logs.inc.php +46 -22
  123. includes/classes/utils-strings.inc.php +134 -41
  124. includes/classes/utils-time.inc.php +130 -49
  125. includes/classes/utils-urls.inc.php +120 -28
  126. includes/classes/utils-users.inc.php +216 -85
  127. includes/classes/wp-footer.inc.php +60 -0
  128. includes/codes.inc.php +15 -13
  129. includes/dropins/bridges/_s2member-bbpress-bridge.php +108 -26
  130. includes/funcs.inc.php +14 -11
  131. includes/functions/api-functions.inc.php +1867 -217
  132. includes/functions/class-autoloader.inc.php +45 -14
  133. includes/functions/deprecated.inc.php +83 -22
  134. includes/hooks.inc.php +33 -20
  135. includes/mailchimp/nc-mcapi.inc.php +0 -1795
  136. includes/menu-pages/api-ops.inc.php +927 -923
  137. includes/menu-pages/bridges.inc.php +0 -150
  138. includes/menu-pages/code-samples/current-user-profile-modification-page-url-2-ops.php +1 -1
  139. includes/menu-pages/code-samples/current-user-profile-modification-page-url-2.php +1 -1
  140. includes/menu-pages/code-samples/idev-signup-tracking-code.php +2 -4
  141. includes/menu-pages/code-samples/idev-sp-tracking-code.php +3 -5
  142. includes/menu-pages/code-samples/sas-signup-tracking-code.php +2 -4
  143. includes/menu-pages/code-samples/sas-sp-tracking-code.php +2 -4
  144. includes/menu-pages/down-ops.inc.php +393 -306
  145. includes/menu-pages/els-ops.inc.php +456 -420
  146. includes/menu-pages/gen-ops.inc.php +1098 -0
  147. includes/menu-pages/info.inc.php +71 -66
  148. includes/menu-pages/integrations.inc.php +179 -0
  149. includes/menu-pages/jquery-json-ps.js +26 -16
  150. includes/menu-pages/jquery-ui-effects.js +13 -0
  151. includes/menu-pages/menu-pages-min.js +1 -1
  152. includes/menu-pages/menu-pages-s-min.js +1 -1
  153. includes/menu-pages/menu-pages-s.css +18 -8
  154. includes/menu-pages/menu-pages-s.js +464 -342
  155. includes/menu-pages/menu-pages.css +237 -79
  156. includes/menu-pages/menu-pages.js +119 -61
  157. includes/menu-pages/mms-ops.inc.php +383 -0
  158. includes/menu-pages/mms-options.inc.php +0 -375
  159. includes/menu-pages/options.inc.php +0 -1721
  160. includes/menu-pages/paypal-buttons.inc.php +788 -780
  161. includes/menu-pages/paypal-ops.inc.php +622 -622
  162. includes/menu-pages/res-ops.inc.php +856 -0
  163. includes/menu-pages/scripting.inc.php +1105 -1100
  164. includes/menu-pages/start.inc.php +247 -224
  165. includes/menu-pages/trk-ops.inc.php +264 -281
  166. includes/menu-pages/ws-mlist.inc.php +97 -0
  167. includes/profile.inc.php +0 -254
  168. includes/s2member-min.js +1 -1
  169. includes/s2member.css +350 -21
  170. includes/s2member.js +314 -95
  171. includes/syscon.inc.php +166 -117
  172. includes/templates/badges/index.php +0 -0
  173. includes/templates/badges/s-badge.html +3 -0
  174. includes/templates/buttons/paypal-checkout-button.html +8 -1
  175. includes/templates/buttons/paypal-sp-checkout-button.html +9 -1
  176. includes/templates/shortcodes/paypal-checkout-button-shortcode.html +1 -1
  177. includes/templates/shortcodes/paypal-sp-checkout-button-shortcode.html +1 -1
  178. readme.txt +89 -35
  179. s2member.php +74 -28
images/amazon-logo.png ADDED
Binary file
images/brand-donations.fla CHANGED
Binary file
images/brand-donations.jpg DELETED
Binary file
images/brand-donations.png ADDED
Binary file
images/logo.fla CHANGED
Binary file
images/logo.png CHANGED
Binary file
images/s2-powered.png ADDED
Binary file
includes/{mailchimp → _xtnls}/index.php RENAMED
File without changes
includes/{markdown → _xtnls/mailchimp}/index.php RENAMED
File without changes
includes/_xtnls/mailchimp/nc-mcapi.inc.php ADDED
@@ -0,0 +1,2515 @@
1
+ <?php
2
+ /**
3
+ * MailChimp® API Class.
4
+ *
5
+ * Copyright {@link http://www.mailchimp.com/ MailChimp®}.
6
+ *
7
+ * Modified by {@link http://www.websharks-inc.com/ WebSharks, Inc.}.
8
+ * Uses a custom class name to avoid conflicts with other instances.
9
+ *
10
+ * This version has also been modified to use:
11
+ * {@link s2Member\Utilities\c_ws_plugin__s2member_utils_urls::remote()}
12
+ *
13
+ * @package Xtnls\MailChimp
14
+ * @since 3.0
15
+ */
16
+ class NC_MCAPI {
17
+ var $version = "1.3";
18
+ var $errorMessage;
19
+ var $errorCode;
20
+
21
+ /**
22
+ * Cache the information on the API location on the server
23
+ */
24
+ var $apiUrl;
25
+
26
+ /**
27
+ * Default to a 300 second timeout on server calls
28
+ */
29
+ var $timeout = 300;
30
+
31
+ /**
32
+ * Default to a 8K chunk size
33
+ */
34
+ var $chunkSize = 8192;
35
+
36
+ /**
37
+ * Cache the user api_key so we only have to log in once per client instantiation
38
+ */
39
+ var $api_key;
40
+
41
+ /**
42
+ * Cache the user api_key so we only have to log in once per client instantiation
43
+ */
44
+ var $secure = false;
45
+
46
+ /**
47
+ * Connect to the MailChimp API for a given list.
48
+ *
49
+ * @param string $apikey Your MailChimp apikey
50
+ * @param string $secure Whether or not this should use a secure connection
51
+ */
52
+ function NC_MCAPI($apikey, $secure=false) {
53
+ $this->secure = $secure;
54
+ $this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
55
+ $this->api_key = $apikey;
56
+ }
57
+ function setTimeout($seconds){
58
+ if (is_int($seconds)){
59
+ $this->timeout = $seconds;
60
+ return true;
61
+ }
62
+ }
63
+ function getTimeout(){
64
+ return $this->timeout;
65
+ }
66
+ function useSecure($val){
67
+ if ($val===true){
68
+ $this->secure = true;
69
+ } else {
70
+ $this->secure = false;
71
+ }
72
+ }
73
+
74
+ /**
75
+ * Unschedule a campaign that is scheduled to be sent in the future
76
+ *
77
+ * @section Campaign Related
78
+ * @example mcapi_campaignUnschedule.php
79
+ * @example xml-rpc_campaignUnschedule.php
80
+ *
81
+ * @param string $cid the id of the campaign to unschedule
82
+ * @return boolean true on success
83
+ */
84
+ function campaignUnschedule($cid) {
85
+ $params = array();
86
+ $params["cid"] = $cid;
87
+ return $this->callServer("campaignUnschedule", $params);
88
+ }
89
+
90
+ /**
91
+ * Schedule a campaign to be sent in the future
92
+ *
93
+ * @section Campaign Related
94
+ * @example mcapi_campaignSchedule.php
95
+ * @example xml-rpc_campaignSchedule.php
96
+ *
97
+ * @param string $cid the id of the campaign to schedule
98
+ * @param string $schedule_time the time to schedule the campaign. For A/B Split "schedule" campaigns, the time for Group A - in YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
99
+ * @param string $schedule_time_b optional -the time to schedule Group B of an A/B Split "schedule" campaign - in YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
100
+ * @return boolean true on success
101
+ */
102
+ function campaignSchedule($cid, $schedule_time, $schedule_time_b=NULL) {
103
+ $params = array();
104
+ $params["cid"] = $cid;
105
+ $params["schedule_time"] = $schedule_time;
106
+ $params["schedule_time_b"] = $schedule_time_b;
107
+ return $this->callServer("campaignSchedule", $params);
108
+ }
109
+
110
+ /**
111
+ * Resume sending an AutoResponder or RSS campaign
112
+ *
113
+ * @section Campaign Related
114
+ *
115
+ * @param string $cid the id of the campaign to pause
116
+ * @return boolean true on success
117
+ */
118
+ function campaignResume($cid) {
119
+ $params = array();
120
+ $params["cid"] = $cid;
121
+ return $this->callServer("campaignResume", $params);
122
+ }
123
+
124
+ /**
125
+ * Pause an AutoResponder orRSS campaign from sending
126
+ *
127
+ * @section Campaign Related
128
+ *
129
+ * @param string $cid the id of the campaign to pause
130
+ * @return boolean true on success
131
+ */
132
+ function campaignPause($cid) {
133
+ $params = array();
134
+ $params["cid"] = $cid;
135
+ return $this->callServer("campaignPause", $params);
136
+ }
137
+
138
+ /**
139
+ * Send a given campaign immediately. For RSS campaigns, this will "start" them.
140
+ *
141
+ * @section Campaign Related
142
+ *
143
+ * @example mcapi_campaignSendNow.php
144
+ * @example xml-rpc_campaignSendNow.php
145
+ *
146
+ * @param string $cid the id of the campaign to send
147
+ * @return boolean true on success
148
+ */
149
+ function campaignSendNow($cid) {
150
+ $params = array();
151
+ $params["cid"] = $cid;
152
+ return $this->callServer("campaignSendNow", $params);
153
+ }
154
+
155
+ /**
156
+ * Send a test of this campaign to the provided email address
157
+ *
158
+ * @section Campaign Related
159
+ *
160
+ * @example mcapi_campaignSendTest.php
161
+ * @example xml-rpc_campaignSendTest.php
162
+ *
163
+ * @param string $cid the id of the campaign to test
164
+ * @param array $test_emails an array of email address to receive the test message
165
+ * @param string $send_type optional by default (null) both formats are sent - "html" or "text" send just that format
166
+ * @return boolean true on success
167
+ */
168
+ function campaignSendTest($cid, $test_emails=array (
169
+ ), $send_type=NULL) {
170
+ $params = array();
171
+ $params["cid"] = $cid;
172
+ $params["test_emails"] = $test_emails;
173
+ $params["send_type"] = $send_type;
174
+ return $this->callServer("campaignSendTest", $params);
175
+ }
176
+
177
+ /**
178
+ * Allows one to test their segmentation rules before creating a campaign using them
179
+ *
180
+ * @section Campaign Related
181
+ * @example mcapi_campaignSegmentTest.php
182
+ * @example xml-rpc_campaignSegmentTest.php
183
+ *
184
+ * @param string $list_id the list to test segmentation on - get lists using lists()
185
+ * @param array $options with 2 keys:
186
+ string "match" controls whether to use AND or OR when applying your options - expects "<strong>any</strong>" (for OR) or "<strong>all</strong>" (for AND)
187
+ array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row must contain 3 keys - "<strong>field</strong>", "<strong>op</strong>", and "<strong>value</strong>" - and possibly a fourth, "<strong>extra</strong>", based on these definitions:
188
+
189
+ Field = "<strong>date</strong>" : Select based on signup date
190
+ Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
191
+ Valid Values:
192
+ string last_campaign_sent uses the date of the last campaign sent
193
+ string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns()
194
+ string YYYY-MM-DD - any date in the form of YYYY-MM-DD - <em>note:</em> anything that appears to start with YYYY will be treated as a date
195
+
196
+ Field = "<strong>interests-X</strong>": where X is the Grouping Id from listInterestGroupings()
197
+ Valid Op(erations): <strong>one</strong> / <strong>none</strong> / <strong>all</strong>
198
+ Valid Values: a comma delimited of interest groups for the list - see listInterestGroupings()
199
+
200
+ Field = "<strong>aim</strong>"
201
+ Valid Op(erations): <strong>open</strong> / <strong>noopen</strong> / <strong>click</strong> / <strong>noclick</strong>
202
+ Valid Values: "<strong>any</strong>" or a valid AIM-enabled Campaign that has been sent
203
+
204
+ Field = "<strong>rating</strong>" : allows matching based on list member ratings
205
+ Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;)
206
+ Valid Values: a number between 0 and 5
207
+
208
+ Field = "<strong>ecomm_prod</strong>" or "<strong>ecomm_prod</strong>": allows matching product and category names from purchases
209
+ Valid Op(erations):
210
+ <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;) / <strong>like</strong> (like '%blah%') / <strong>nlike</strong> (not like '%blah%') / <strong>starts</strong> (like 'blah%') / <strong>ends</strong> (like '%blah')
211
+ Valid Values: any string
212
+
213
+ Field = "<strong>ecomm_spent_one</strong>" or "<strong>ecomm_spent_all</strong>" : allows matching purchase amounts on a single order or all orders
214
+ Valid Op(erations): <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;)
215
+ Valid Values: a number
216
+
217
+ Field = "<strong>ecomm_date</strong>" : allow matching based on order dates
218
+ Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
219
+ Valid Values:
220
+ string YYYY-MM-DD - any date in the form of YYYY-MM-DD
221
+
222
+ Field = "<strong>social_gender</strong>" : allows matching against the gender acquired from SocialPro
223
+ Valid Op(eration): <strong>eq</strong> (is) / <strong>ne</strong> (is not)
224
+ Valid Values: male, female
225
+
226
+ Field = "<strong>social_age</strong>" : allows matching against the age acquired from SocialPro
227
+ Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;)
228
+ Valid Values: any number
229
+
230
+ Field = "<strong>social_influence</strong>" : allows matching against the influence acquired from SocialPro
231
+ Valid Op(erations): <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;)
232
+ Valid Values: a number between 0 and 5
233
+
234
+ Field = "<strong>social_network</strong>" :
235
+ Valid Op(erations): <strong>member</strong> (is a member of) / <strong>notmember</strong> (is not a member of)
236
+ Valid Values: twitter, facebook, myspace, linkedin, flickr
237
+
238
+ Field = "<strong>static_segment</strong>" :
239
+ Valid Op(eration): <strong>eq</strong> (is in) / <strong>ne</strong> (is not in)
240
+ Valid Values: an int - get from listStaticSegments()
241
+
242
+ Field = An <strong>Address</strong> Merge Var. Use <strong>Merge0-Merge30</strong> or the <strong>Custom Tag</strong> you've setup for your merge field - see listMergeVars(). Note, Address fields can still be used with the default operations below - this section is broken out solely to highlight the differences in using the geolocation routines.
243
+ Valid Op(erations): <strong>geoin</strong>
244
+ Valid Values: The number of miles an address should be within
245
+ Extra Value: The Zip Code to be used as the center point
246
+
247
+ Default Field = A Merge Var. Use <strong>Merge0-Merge30</strong> or the <strong>Custom Tag</strong> you've setup for your merge field - see listMergeVars()
248
+ Valid Op(erations):
249
+ <strong>eq</strong> (=) / <strong>ne</strong> (!=) / <strong>gt</strong> (&gt;) / <strong>lt</strong> (&lt;) / <strong>like</strong> (like '%blah%') / <strong>nlike</strong> (not like '%blah%') / <strong>starts</strong> (like 'blah%') / <strong>ends</strong> (like '%blah')
250
+ Valid Values: any string
251
+ * @return int total The total number of subscribers matching your segmentation options
252
+ */
253
+ function campaignSegmentTest($list_id, $options) {
254
+ $params = array();
255
+ $params["list_id"] = $list_id;
256
+ $params["options"] = $options;
257
+ return $this->callServer("campaignSegmentTest", $params);
258
+ }
259
+
260
+ /**
261
+ * Create a new draft campaign to send. You <strong>can not</strong> have more than 32,000 campaigns in your account.
262
+ *
263
+ * @section Campaign Related
264
+ * @example mcapi_campaignCreate.php
265
+ * @example xml-rpc_campaignCreate.php
266
+ * @example xml-rpc_campaignCreateABSplit.php
267
+ * @example xml-rpc_campaignCreateRss.php
268
+ *
269
+ * @param string $type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "trans", "auto"
270
+ * @param array $options a hash of the standard options for this campaign :
271
+ string list_id the list to send this campaign to- get lists using lists()
272
+ string subject the subject line for your campaign message
273
+ string from_email the From: email address for your campaign message
274
+ string from_name the From: name for your campaign message (not an email address)
275
+ string to_name the To: name recipients will see (not email address)
276
+ int template_id optional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
277
+ int gallery_template_id optional - use a template from the public gallery to generate the HTML content of the campaign (takes precendence over base template options)
278
+ int base_template_id optional - use this a base/start-from-scratch template to generate the HTML content of the campaign
279
+ int folder_id optional - automatically file the new campaign in the folder_id passed. Get using folders() - note that Campaigns and Autoresponders have separate folder setupsn
280
+ array tracking optional - set which recipient actions will be tracked, as a struct of boolean values with the following keys: "opens", "html_clicks", and "text_clicks". By default, opens and HTML clicks will be tracked. Click tracking can not be disabled for Free accounts.
281
+ string title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
282
+ boolean authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
283
+ array analytics optional - if provided, use a struct with "service type" as a key and the "service tag" as a value. For Google, this should be "google"=>"your_google_analytics_key_here". Note that only "google" is currently supported - a Google Analytics tags will be added to all links in the campaign with this string attached. Others may be added in the future
284
+ boolean auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
285
+ boolean inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
286
+ boolean generate_text optional Whether of not to auto-generate your Text content from the HTML content. Note that this will be ignored if the Text part of the content passed is not empty, defaults to false.
287
+ boolean auto_tweet optional If set, this campaign will be auto-tweeted when it is sent - defaults to false. Note that if a Twitter account isn't linked, this will be silently ignored.
288
+ boolean timewarp optional If set, this campaign must be scheduled 24 hours in advance of sending - default to false. Only valid for "regular" campaigns and "absplit" campaigns that split on schedule_time.
289
+ boolean ecomm360 optional If set, our <a href="http://www.mailchimp.com/blog/ecommerce-tracking-plugin/" target="_blank">Ecommerce360 tracking</a> will be enabled for links in the campaign
290
+
291
+ * @param array $content the content for this campaign - use a struct with the following keys:
292
+ string html for pasted HTML content
293
+ string text for the plain-text version
294
+ string url to have us pull in content from a URL. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
295
+ string archive to send a Base64 encoded archive file for us to import all media from. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
296
+ string archive_type optional - only necessary for the "archive" option. Supported formats are: zip, tar.gz, tar.bz2, tar, tgz, tbz . If not included, we will default to zip
297
+
298
+ If you chose a template instead of pasting in your HTML content, then use "html_" followed by the template sections as keys - for example, use a key of "html_MAIN" to fill in the "MAIN" section of a template. Supported template sections include: "html_HEADER", "html_MAIN", "html_SIDECOLUMN", and "html_FOOTER"
299
+ * @param array $segment_opts optional - if you wish to do Segmentation with this campaign this array should contain: see campaignSegmentTest(). It's suggested that you test your options against campaignSegmentTest(). Also, "trans" campaigns <strong>do not</strong> support segmentation.
300
+ * @param array $type_opts optional -
301
+ For RSS Campaigns this, array should contain:
302
+ string url the URL to pull RSS content from - it will be verified and must exist
303
+ string schedule optional one of "daily", "weekly", "monthly" - defaults to "daily"
304
+ string schedule_hour optional an hour between 0 and 24 - default to 4 (4am <em>local time</em>) - applies to all schedule types
305
+ string schedule_weekday optional for "weekly" only, a number specifying the day of the week to send: 0 (Sunday) - 6 (Saturday) - defaults to 1 (Monday)
306
+ string schedule_monthday optional for "monthly" only, a number specifying the day of the month to send (1 - 28) or "last" for the last day of a given month. Defaults to the 1st day of the month
307
+
308
+ For A/B Split campaigns, this array should contain:
309
+ string split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
310
+ string pick_winner How the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
311
+ int wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
312
+ int wait_time optional the number of units to wait before auto-selecting a winner - defaults to 1, so if not set, a winner will be selected after 1 Day.
313
+ int split_size optional this is a percentage of what size the Campaign's List plus any segmentation options results in. "schedule" type forces 50%, all others default to 10%
314
+ string from_name_a optional sort of, required when split_test is "from_name"
315
+ string from_name_b optional sort of, required when split_test is "from_name"
316
+ string from_email_a optional sort of, required when split_test is "from_name"
317
+ string from_email_b optional sort of, required when split_test is "from_name"
318
+ string subject_a optional sort of, required when split_test is "subject"
319
+ string subject_b optional sort of, required when split_test is "subject"
320
+
321
+ For AutoResponder campaigns, this array should contain:
322
+ string offset-units one of "day", "week", "month", "year" - required
323
+ string offset-time optional, sort of - the number of units must be a number greater than 0 for signup based autoresponders
324
+ string offset-dir either "before" or "after"
325
+ string event optional "signup" (default) to base this on double-optin signup, "date" or "annual" to base this on merge field in the list
326
+ string event-datemerge optional sort of, this is required if the event is "date" or "annual"
327
+
328
+ *
329
+ * @return string the ID for the created campaign
330
+ */
331
+ function campaignCreate($type, $options, $content, $segment_opts=NULL, $type_opts=NULL) {
332
+ $params = array();
333
+ $params["type"] = $type;
334
+ $params["options"] = $options;
335
+ $params["content"] = $content;
336
+ $params["segment_opts"] = $segment_opts;
337
+ $params["type_opts"] = $type_opts;
338
+ return $this->callServer("campaignCreate", $params);
339
+ }
340
+
341
+ /** Update just about any setting for a campaign that has <em>not</em> been sent. See campaignCreate() for details.
342
+ *
343
+ *
344
+ * Caveats:<br/><ul>
345
+ * <li>If you set list_id, all segmentation options will be deleted and must be re-added.</li>
346
+ * <li>If you set template_id, you need to follow that up by setting it's 'content'</li>
347
+ * <li>If you set segment_opts, you should have tested your options against campaignSegmentTest() as campaignUpdate() will not allow you to set a segment that includes no members.</li></ul>
348
+ * @section Campaign Related
349
+ *
350
+ * @example mcapi_campaignUpdate.php
351
+ * @example mcapi_campaignUpdateAB.php
352
+ * @example xml-rpc_campaignUpdate.php
353
+ * @example xml-rpc_campaignUpdateAB.php
354
+ *
355
+ * @param string $cid the Campaign Id to update
356
+ * @param string $name the parameter name ( see campaignCreate() ). For items in the <strong>options</strong> array, this will be that parameter's name (subject, from_email, etc.). Additional parameters will be that option name (content, segment_opts). "type_opts" will be the name of the type - rss, auto, trans, etc.
357
+ * @param mixed $value an appropriate value for the parameter ( see campaignCreate() ). For items in the <strong>options</strong> array, this will be that parameter's value. For additional parameters, this is the same value passed to them.
358
+ * @return boolean true if the update succeeds, otherwise an error will be thrown
359
+ */
360
+ function campaignUpdate($cid, $name, $value) {
361
+ $params = array();
362
+ $params["cid"] = $cid;
363
+ $params["name"] = $name;
364
+ $params["value"] = $value;
365
+ return $this->callServer("campaignUpdate", $params);
366
+ }
367
+
368
+ /** Replicate a campaign.
369
+ *
370
+ * @section Campaign Related
371
+ *
372
+ * @example mcapi_campaignReplicate.php
373
+ *
374
+ * @param string $cid the Campaign Id to replicate
375
+ * @return string the id of the replicated Campaign created, otherwise an error will be thrown
376
+ */
377
+ function campaignReplicate($cid) {
378
+ $params = array();
379
+ $params["cid"] = $cid;
380
+ return $this->callServer("campaignReplicate", $params);
381
+ }
382
+
383
+ /** Delete a campaign. Seriously, "poof, gone!" - be careful!
384
+ *
385
+ * @section Campaign Related
386
+ *
387
+ * @example mcapi_campaignDelete.php
388
+ *
389
+ * @param string $cid the Campaign Id to delete
390
+ * @return boolean true if the delete succeeds, otherwise an error will be thrown
391
+ */
392
+ function campaignDelete($cid) {
393
+ $params = array();
394
+ $params["cid"] = $cid;
395
+ return $this->callServer("campaignDelete", $params);
396
+ }
397
+
398
+ /**
399
+ * Get the list of campaigns and their details matching the specified filters
400
+ *
401
+ * @section Campaign Related
402
+ * @example mcapi_campaigns.php
403
+ * @example xml-rpc_campaigns.php
404
+ *
405
+ * @param array $filters a hash of filters to apply to this query - all are optional:
406
+ string campaign_id optional - return a single campaign using a know campaign_id
407
+ string list_id optional - the list to send this campaign to- get lists using lists(). Accepts multiples separated by commas when not using exact matching.
408
+ int folder_id optional - only show campaigns from this folder id - get folders using campaignFolders(). Accepts multiples separated by commas when not using exact matching.
409
+ int template_id optional - only show campaigns using this template id - get templates using templates(). Accepts multiples separated by commas when not using exact matching.
410
+ string status optional - return campaigns of a specific status - one of "sent", "save", "paused", "schedule", "sending". Accepts multiples separated by commas when not using exact matching.
411
+ string type optional - return campaigns of a specific type - one of "regular", "plaintext", "absplit", "rss", "trans", "auto". Accepts multiples separated by commas when not using exact matching.
412
+ string from_name optional - only show campaigns that have this "From Name"
413
+ string from_email optional - only show campaigns that have this "Reply-to Email"
414
+ string title optional - only show campaigns that have this title
415
+ string subject optional - only show campaigns that have this subject
416
+ string sendtime_start optional - only show campaigns that have been sent since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
417
+ string sendtime_end optional - only show campaigns that have been sent before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
418
+ boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true. Using this disables the use of any filters that accept multiples.
419
+ * @param int $start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data (page 0)
420
+ * @param int $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=1000)
421
+ * @return array an array containing a count of all matching campaigns and the specific ones for the current page (see Returned Fields for description)
422
+ * @returnf int total the total number of campaigns matching the filters passed in
423
+ * @returnf array data the data for each campaign being returned
424
+ string id Campaign Id (used for all other campaign functions)
425
+ int web_id The Campaign id used in our web app, allows you to create a link directly to it
426
+ string list_id The List used for this campaign
427
+ int folder_id The Folder this campaign is in
428
+ int template_id The Template this campaign uses
429
+ string content_type How the campaign's content is put together - one of 'template', 'html', 'url'
430
+ string title Title of the campaign
431
+ string type The type of campaign this is (regular,plaintext,absplit,rss,inspection,trans,auto)
432
+ string create_time Creation time for the campaign
433
+ string send_time Send time for the campaign - also the scheduled time for scheduled campaigns.
434
+ int emails_sent Number of emails email was sent to
435
+ string status Status of the given campaign (save,paused,schedule,sending,sent)
436
+ string from_name From name of the given campaign
437
+ string from_email Reply-to email of the given campaign
438
+ string subject Subject of the given campaign
439
+ string to_name Custom "To:" email string using merge variables
440
+ string archive_url Archive link for the given campaign
441
+ boolean inline_css Whether or not the campaign content's css was auto-inlined
442
+ string analytics Either "google" if enabled or "N" if disabled
443
+ string analytics_tag The name/tag the campaign's links were tagged with if analytics were enabled.
444
+ boolean authenticate Whether or not the campaign was authenticated
445
+ boolean ecomm360 Whether or not ecomm360 tracking was appended to links
446
+ boolean auto_tweet Whether or not the campaign was auto tweeted after sending
447
+ string auto_fb_post A comma delimited list of Facebook Profile/Page Ids the campaign was posted to after sending. If not used, blank.
448
+ boolean auto_footer Whether or not the auto_footer was manually turned on
449
+ boolean timewarp Whether or not the campaign used Timewarp
450
+ boolean timewarp_schedule The time, in GMT, that the Timewarp campaign is being sent. For A/B Split campaigns, this is blank and is instead in their schedule_a and schedule_b in the type_opts array
451
+ array tracking containing "text_clicks", "html_clicks", and "opens" as boolean values representing whether or not they were enabled
452
+ string segment_text a string marked-up with HTML explaining the segment used for the campaign in plain English
453
+ array segment_opts the segment used for the campaign - can be passed to campaignSegmentTest() or campaignCreate()
454
+ array type_opts the type-specific options for the campaign - can be passed to campaignCreate()
455
+ */
456
+ function campaigns($filters=array (
457
+ ), $start=0, $limit=25) {
458
+ $params = array();
459
+ $params["filters"] = $filters;
460
+ $params["start"] = $start;
461
+ $params["limit"] = $limit;
462
+ return $this->callServer("campaigns", $params);
463
+ }
464
+
465
+ /**
466
+ * Given a list and a campaign, get all the relevant campaign statistics (opens, bounces, clicks, etc.)
467
+ *
468
+ * @section Campaign Stats
469
+ *
470
+ * @example mcapi_campaignStats.php
471
+ * @example xml-rpc_campaignStats.php
472
+ *
473
+ * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
474
+ * @return array struct of the statistics for this campaign
475
+ * @returnf int syntax_errors Number of email addresses in campaign that had syntactical errors.
476
+ * @returnf int hard_bounces Number of email addresses in campaign that hard bounced.
477
+ * @returnf int soft_bounces Number of email addresses in campaign that soft bounced.
478
+ * @returnf int unsubscribes Number of email addresses in campaign that unsubscribed.
479
+ * @returnf int abuse_reports Number of email addresses in campaign that reported campaign for abuse.
480
+ * @returnf int forwards Number of times email was forwarded to a friend.
481
+ * @returnf int forwards_opens Number of times a forwarded email was opened.
482
+ * @returnf int opens Number of times the campaign was opened.
483
+ * @returnf date last_open Date of the last time the email was opened.
484
+ * @returnf int unique_opens Number of people who opened the campaign.
485
+ * @returnf int clicks Number of times a link in the campaign was clicked.
486
+ * @returnf int unique_clicks Number of unique recipient/click pairs for the campaign.
487
+ * @returnf date last_click Date of the last time a link in the email was clicked.
488
+ * @returnf int users_who_clicked Number of unique recipients who clicked on a link in the campaign.
489
+ * @returnf int emails_sent Number of email addresses campaign was sent to.
490
+ * @returnf array absplit If this was an absplit campaign, stats for the A and B groups will be returned
491
+ int bounces_a bounces for the A group
492
+ int bounces_b bounces for the B group
493
+ int forwards_a forwards for the A group
494
+ int forwards_b forwards for the B group
495
+ int abuse_reports_a abuse reports for the A group
496
+ int abuse_reports_b abuse reports for the B group
497
+ int unsubs_a unsubs for the A group
498
+ int unsubs_b unsubs for the B group
499
+ int recipients_click_a clicks for the A group
500
+ int recipients_click_b clicks for the B group
501
+ int forwards_opens_a opened forwards for the A group
502
+ int forwards_opens_b opened forwards for the A group
503
+ * @returnf array timewarp If this campaign was a Timewarp campaign, an array of stats from each timezone for it, with the GMT offset as they key. Each timezone will contain:
504
+ int opens opens for this timezone
505
+ string last_open the date/time of the last open for this timezone
506
+ int unique_opens the unique opens for this timezone
507
+ int clicks the total clicks for this timezone
508
+ string last_click the date/time of the last click for this timezone
509
+ int unique_opens the unique clicks for this timezone
510
+ int bounces the total bounces for this timezone
511
+ int total the total number of members sent to in this timezone
512
+ int sent the total number of members delivered to in this timezone
513
+ */
514
+ function campaignStats($cid) {
515
+ $params = array();
516
+ $params["cid"] = $cid;
517
+ return $this->callServer("campaignStats", $params);
518
+ }
519
+
520
+ /**
521
+ * Get an array of the urls being tracked, and their click counts for a given campaign
522
+ *
523
+ * @section Campaign Stats
524
+ *
525
+ * @example mcapi_campaignClickStats.php
526
+ * @example xml-rpc_campaignClickStats.php
527
+ *
528
+ * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
529
+ * @return struct urls will be keys and contain their associated statistics:
530
+ * @returnf int clicks Number of times the specific link was clicked
531
+ * @returnf int unique Number of unique people who clicked on the specific link
532
+ */
533
+ function campaignClickStats($cid) {
534
+ $params = array();
535
+ $params["cid"] = $cid;
536
+ return $this->callServer("campaignClickStats", $params);
537
+ }
538
+
539
+ /**
540
+ * Get the top 5 performing email domains for this campaign. Users want more than 5 should use campaign campaignEmailStatsAIM()
541
+ * or campaignEmailStatsAIMAll() and generate any additional stats they require.
542
+ *
543
+ * @section Campaign Stats
544
+ *
545
+ * @example mcapi_campaignEmailDomainPerformance.php
546
+ *
547
+ * @param string $cid the campaign id to pull email domain performance for (can be gathered using campaigns())
548
+ * @return array domains email domains and their associated stats
549
+ * @returnf string domain Domain name or special "Other" to roll-up stats past 5 domains
550
+ * @returnf int total_sent Total Email across all domains - this will be the same in every row
551
+ * @returnf int emails Number of emails sent to this domain
552
+ * @returnf int bounces Number of bounces
553
+ * @returnf int opens Number of opens
554
+ * @returnf int clicks Number of clicks
555
+ * @returnf int unsubs Number of unsubs
556
+ * @returnf int delivered Number of deliveries
557
+ * @returnf int emails_pct Percentage of emails that went to this domain (whole number)
558
+ * @returnf int bounces_pct Percentage of bounces from this domain (whole number)
559
+ * @returnf int opens_pct Percentage of opens from this domain (whole number)
560
+ * @returnf int clicks_pct Percentage of clicks from this domain (whole number)
561
+ * @returnf int unsubs_pct Percentage of unsubs from this domain (whole number)
562
+ */
563
+ function campaignEmailDomainPerformance($cid) {
564
+ $params = array();
565
+ $params["cid"] = $cid;
566
+ return $this->callServer("campaignEmailDomainPerformance", $params);
567
+ }
568
+
569
+ /**
570
+ * Get all email addresses the campaign was successfully sent to (ie, no bounces)
571
+ *
572
+ * @section Campaign Stats
573
+ *
574
+ * @param string $cid the campaign id to pull members for (can be gathered using campaigns())
575
+ * @param string $status optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
576
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
577
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
578
+ * @return array a total of all matching emails and the specific emails for this page
579
+ * @returnf int total the total number of members for the campaign and status
580
+ * @returnf array data the full campaign member records
581
+ string email the email address sent to
582
+ string status the status of the send - one of 'sent', 'hard', 'soft'
583
+ string absplit_group if this was an absplit campaign, one of 'a','b', or 'winner'
584
+ string tz_group if this was an timewarp campaign the timezone GMT offset the member was included in
585
+ */
586
+ function campaignMembers($cid, $status=NULL, $start=0, $limit=1000) {
587
+ $params = array();
588
+ $params["cid"] = $cid;
589
+ $params["status"] = $status;
590
+ $params["start"] = $start;
591
+ $params["limit"] = $limit;
592
+ return $this->callServer("campaignMembers", $params);
593
+ }
594
+
595
+ /**
596
+ * <strong>DEPRECATED</strong> Get all email addresses with Hard Bounces for a given campaign
597
+ *
598
+ * @deprecated See campaignMembers() for a replacement
599
+ *
600
+ * @section Campaign Stats
601
+ *
602
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
603
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
604
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
605
+ * @return array a total of all hard bounced emails and the specific emails for this page
606
+ * @returnf int total the total number of hard bounces for the campaign
607
+ * @returnf array data the full email addresses that bounced
608
+ string email the email address that bounced
609
+ */
610
+ function campaignHardBounces($cid, $start=0, $limit=1000) {
611
+ $params = array();
612
+ $params["cid"] = $cid;
613
+ $params["start"] = $start;
614
+ $params["limit"] = $limit;
615
+ return $this->callServer("campaignHardBounces", $params);
616
+ }
617
+
618
+ /**
619
+ * <strong>DEPRECATED</strong> Get all email addresses with Soft Bounces for a given campaign
620
+ *
621
+ * @deprecated See campaignMembers() for a replacement
622
+ *
623
+ * @section Campaign Stats
624
+ *
625
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
626
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
627
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
628
+ * @return array a total of all soft bounced emails and the specific emails for this page
629
+ * @returnf int total the total number of soft bounces for the campaign
630
+ * @returnf array data the full email addresses that bounced
631
+ string email the email address that bounced
632
+ */
633
+ function campaignSoftBounces($cid, $start=0, $limit=1000) {
634
+ $params = array();
635
+ $params["cid"] = $cid;
636
+ $params["start"] = $start;
637
+ $params["limit"] = $limit;
638
+ return $this->callServer("campaignSoftBounces", $params);
639
+ }
640
+
641
+ /**
642
+ * Get all unsubscribed email addresses for a given campaign
643
+ *
644
+ * @section Campaign Stats
645
+ *
646
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
647
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
648
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
649
+ * @return array email addresses that unsubscribed from this campaign along with reasons, if given
650
+ * @return array a total of all unsubscribed emails and the specific emails for this page
651
+ * @returnf int total the total number of unsubscribes for the campaign
652
+ * @returnf array data the full email addresses that unsubscribed
653
+ string email the email address that unsubscribed
654
+ string reason For unsubscribes only - the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
655
+ string reason_text For unsubscribes only - if the reason is OTHER, the text entered.
656
+ */
657
+ function campaignUnsubscribes($cid, $start=0, $limit=1000) {
658
+ $params = array();
659
+ $params["cid"] = $cid;
660
+ $params["start"] = $start;
661
+ $params["limit"] = $limit;
662
+ return $this->callServer("campaignUnsubscribes", $params);
663
+ }
664
+
665
+ /**
666
+ * Get all email addresses that complained about a given campaign
667
+ *
668
+ * @section Campaign Stats
669
+ *
670
+ * @example mcapi_campaignAbuseReports.php
671
+ *
672
+ * @param string $cid the campaign id to pull abuse reports for (can be gathered using campaigns())
673
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
674
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
675
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
676
+ * @return array reports the abuse reports for this campaign
677
+ * @returnf string date date/time the abuse report was received and processed
678
+ * @returnf string email the email address that reported abuse
679
+ * @returnf string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
680
+ */
681
+ function campaignAbuseReports($cid, $since=NULL, $start=0, $limit=500) {
682
+ $params = array();
683
+ $params["cid"] = $cid;
684
+ $params["since"] = $since;
685
+ $params["start"] = $start;
686
+ $params["limit"] = $limit;
687
+ return $this->callServer("campaignAbuseReports", $params);
688
+ }
689
+
690
+ /**
691
+ * Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
692
+ * suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
693
+ *
694
+ * @section Campaign Stats
695
+ *
696
+ * @example mcapi_campaignAdvice.php
697
+ *
698
+ * @param string $cid the campaign id to pull advice text for (can be gathered using campaigns())
699
+ * @return array advice on the campaign's performance
700
+ * @returnf msg the advice message
701
+ * @returnf type the "type" of the message. one of: negative, positive, or neutral
702
+ */
703
+ function campaignAdvice($cid) {
704
+ $params = array();
705
+ $params["cid"] = $cid;
706
+ return $this->callServer("campaignAdvice", $params);
707
+ }
708
+
709
+ /**
710
+ * Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
711
+ *
712
+ * @section Campaign Stats
713
+ *
714
+ * @example mcapi_campaignAnalytics.php
715
+ *
716
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
717
+ * @return array analytics we've collected for the passed campaign.
718
+ * @returnf int visits number of visits
719
+ * @returnf int pages number of page views
720
+ * @returnf int new_visits new visits recorded
721
+ * @returnf int bounces vistors who "bounced" from your site
722
+ * @returnf double time_on_site the total time visitors spent on your sites
723
+ * @returnf int goal_conversions number of goals converted
724
+ * @returnf double goal_value value of conversion in dollars
725
+ * @returnf double revenue revenue generated by campaign
726
+ * @returnf int transactions number of transactions tracked
727
+ * @returnf int ecomm_conversions number Ecommerce transactions tracked
728
+ * @returnf array goals an array containing goal names and number of conversions
729
+ */
730
+ function campaignAnalytics($cid) {
731
+ $params = array();
732
+ $params["cid"] = $cid;
733
+ return $this->callServer("campaignAnalytics", $params);
734
+ }
735
+
736
+ /**
737
+ * Retrieve the countries and number of opens tracked for each. Email address are not returned.
738
+ *
739
+ * @section Campaign Stats
740
+ *
741
+ *
742
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
743
+ * @return array countries an array of countries where opens occurred
744
+ * @returnf string code The ISO3166 2 digit country code
745
+ * @returnf string name A version of the country name, if we have it
746
+ * @returnf int opens The total number of opens that occurred in the country
747
+ * @returnf bool region_detail Whether or not a subsequent call to campaignGeoOpensByCountry() will return anything
748
+ */
749
+ function campaignGeoOpens($cid) {
750
+ $params = array();
751
+ $params["cid"] = $cid;
752
+ return $this->callServer("campaignGeoOpens", $params);
753
+ }
754
+
755
+ /**
756
+ * Retrieve the regions and number of opens tracked for a certain country. Email address are not returned.
757
+ *
758
+ * @section Campaign Stats
759
+ *
760
+ *
761
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
762
+ * @param string $code An ISO3166 2 digit country code
763
+ * @return array regions an array of regions within the provided country where opens occurred.
764
+ * @returnf string code An internal code for the region. When this is blank, it indicates we know the country, but not the region
765
+ * @returnf string name The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
766
+ * @returnf int opens The total number of opens that occurred in the country
767
+ */
768
+ function campaignGeoOpensForCountry($cid, $code) {
769
+ $params = array();
770
+ $params["cid"] = $cid;
771
+ $params["code"] = $code;
772
+ return $this->callServer("campaignGeoOpensForCountry", $params);
773
+ }
774
+
775
+ /**
776
+ * Retrieve the tracked eepurl mentions on Twitter
777
+ *
778
+ * @section Campaign Stats
779
+ *
780
+ *
781
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
782
+ * @return array stats an array containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
783
+ * @returnf array twitter various Twitter related stats
784
+ int tweets Total number of tweets seen
785
+ string first_tweet date and time of the first tweet seen
786
+ string last_tweet date and time of the last tweet seen
787
+ int retweets Total number of retweets seen
788
+ string first_retweet date and time of the first retweet seen
789
+ string last_retweet date and time of the last retweet seen
790
+ array statuses an array of statuses recorded inclduing the status, screen_name, status_id, and datetime fields plus an is_retweet flag
791
+ * @returnf array clicks stats related to click-throughs on the eepurl
792
+ int clicks Total number of clicks seen
793
+ string first_click date and time of the first click seen
794
+ string last_click date and time of the first click seen
795
+ array locations an array of geographic locations including country, region, and total clicks
796
+ * @returnf array referrers an array of arrays, each containing
797
+ string referrer the referrer, truncated to 100 bytes
798
+ int clicks Total number of clicks seen from this referrer
799
+ string first_click date and time of the first click seen from this referrer
800
+ string last_click date and time of the first click seen from this referrer
801
+ */
802
+ function campaignEepUrlStats($cid) {
803
+ $params = array();
804
+ $params["cid"] = $cid;
805
+ return $this->callServer("campaignEepUrlStats", $params);
806
+ }
807
+
808
+ /**
809
+ * Retrieve the most recent full bounce message for a specific email address on the given campaign.
810
+ * Messages over 30 days old are subject to being removed
811
+ *
812
+ *
813
+ * @section Campaign Stats
814
+ *
815
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
816
+ * @param string $email the email address or unique id of the member to pull a bounce message for.
817
+ * @return array the full bounce message for this email+campaign along with some extra data.
818
+ * @returnf string date date/time the bounce was received and processed
819
+ * @returnf string email the email address that bounced
820
+ * @returnf string message the entire bounce message received
821
+ */
822
+ function campaignBounceMessage($cid, $email) {
823
+ $params = array();
824
+ $params["cid"] = $cid;
825
+ $params["email"] = $email;
826
+ return $this->callServer("campaignBounceMessage", $params);
827
+ }
828
+
829
+ /**
830
+ * Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
831
+ * of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
832
+ * message over 30 days old are subject to being removed
833
+ *
834
+ * @section Campaign Stats
835
+ *
836
+ * @example mcapi_campaignBounceMessages.php
837
+ *
838
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
839
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
840
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 50
841
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD format in <strong>GMT</strong> (we only store the date, not the time)
842
+ * @return array bounces the full bounce messages for this campaign
843
+ * @returnf int total that total number of bounce messages for the campaign
844
+ * @returnf array data an array containing the data for this page
845
+ string date date/time the bounce was received and processed
846
+ string email the email address that bounced
847
+ string message the entire bounce message received
848
+ */
849
+ function campaignBounceMessages($cid, $start=0, $limit=25, $since=NULL) {
850
+ $params = array();
851
+ $params["cid"] = $cid;
852
+ $params["start"] = $start;
853
+ $params["limit"] = $limit;
854
+ $params["since"] = $since;
855
+ return $this->callServer("campaignBounceMessages", $params);
856
+ }
857
+
858
+ /**
859
+ * Retrieve the Ecommerce Orders tracked by campaignEcommOrderAdd()
860
+ *
861
+ * @section Campaign Stats
862
+ *
863
+ * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
864
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
865
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
866
+ * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
867
+ * @return array the total matching orders and the specific orders for the requested page
868
+ * @returnf int total the total matching orders
869
+ * @returnf array data the actual data for each order being returned
870
+ string store_id the store id generated by the plugin used to uniquely identify a store
871
+ string store_name the store name collected by the plugin - often the domain name
872
+ string order_id the internal order id the store tracked this order by
873
+ string email the email address that received this campaign and is associated with this order
874
+ double order_total the order total
875
+ double tax_total the total tax for the order (if collected)
876
+ double ship_total the shipping total for the order (if collected)
877
+ string order_date the date the order was tracked - from the store if possible, otherwise the GMT time we recieved it
878
+ array lines containing detail of the order - product, category, quantity, item cost
879
+ */
880
+ function campaignEcommOrders($cid, $start=0, $limit=100, $since=NULL) {
881
+ $params = array();
882
+ $params["cid"] = $cid;
883
+ $params["start"] = $start;
884
+ $params["limit"] = $limit;
885
+ $params["since"] = $since;
886
+ return $this->callServer("campaignEcommOrders", $params);
887
+ }
888
+
889
+ /**
890
+ * Get the URL to a customized <a href="http://eepurl.com/gKmL" target="_blank">VIP Report</a> for the specified campaign and optionally send an email to someone with links to it. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)
891
+ *
892
+ * @section Campaign Related
893
+ *
894
+ * @param string $cid the campaign id to share a report for (can be gathered using campaigns())
895
+ * @param array $opts optional various parameters which can be used to configure the shared report
896
+ string header_type optional - "text" or "image', defaults to "text'
897
+ string header_data optional - if "header_type" is text, the text to display. if "header_type" is "image" a valid URL to an image file. Note that images will be resized to be no more than 500x150. Defaults to the Accounts Company Name.
898
+ boolean secure optional - whether to require a password for the shared report. defaults to "true"
899
+ string password optional - if secure is true and a password is not included, we will generate one. It is always returned.
900
+ string to_email optional - optional, email address to share the report with - no value means an email will not be sent
901
+ array theme optional - an array containing either 3 or 6 character color code values for: "bg_color", "header_color", "current_tab", "current_tab_text", "normal_tab", "normal_tab_text", "hover_tab", "hover_tab_text"
902
+ string css_url optional - a link to an external CSS file to be included after our default CSS (http://vip-reports.net/css/vip.css) <strong>only if</strong> loaded via the "secure_url" - max 255 bytes
903
+ * @return struct Struct containing details for the shared report
904
+ * @returnf string title The Title of the Campaign being shared
905
+ * @returnf string url The URL to the shared report
906
+ * @returnf string secure_url The URL to the shared report, including the password (good for loading in an IFRAME). For non-secure reports, this will not be returned
907
+ * @returnf string password If secured, the password for the report, otherwise this field will not be returned
908
+ */
909
+ function campaignShareReport($cid, $opts=array (
910
+ )) {
911
+ $params = array();
912
+ $params["cid"] = $cid;
913
+ $params["opts"] = $opts;
914
+ return $this->callServer("campaignShareReport", $params);
915
+ }
916
+
917
+ /**
918
+ * Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content
919
+ *
920
+ * @section Campaign Related
921
+ *
922
+ * @param string $cid the campaign id to get content for (can be gathered using campaigns())
923
+ * @param bool $for_archive optional controls whether we return the Archive version (true) or the Raw version (false), defaults to true
924
+ * @return struct Struct containing all content for the campaign (see Returned Fields for details
925
+ * @returnf string html The HTML content used for the campgain with merge tags intact
926
+ * @returnf string text The Text content used for the campgain with merge tags intact
927
+ */
928
+ function campaignContent($cid, $for_archive=true) {
929
+ $params = array();
930
+ $params["cid"] = $cid;
931
+ $params["for_archive"] = $for_archive;
932
+ return $this->callServer("campaignContent", $params);
933
+ }
934
+
935
+ /**
936
+ * Get the HTML template content sections for a campaign. Note that this <strong>will</strong> return very jagged, non-standard results based on the template
937
+ * a campaign is using. You only want to use this if you want to allow editing template sections in your applicaton.
938
+ *
939
+ * @section Campaign Related
940
+ *
941
+ * @param string $cid the campaign id to get content for (can be gathered using campaigns())
942
+ * @return array array containing all content section for the campaign -
943
+ */
944
+ function campaignTemplateContent($cid) {
945
+ $params = array();
946
+ $params["cid"] = $cid;
947
+ return $this->callServer("campaignTemplateContent", $params);
948
+ }
949
+
950
+ /**
951
+ * Retrieve the list of email addresses that opened a given campaign with how many times they opened - note: this AIM function is free and does
952
+ * not actually require the AIM module to be installed
953
+ *
954
+ * @section Campaign Report Data
955
+ *
956
+ * @param string $cid the campaign id to get opens for (can be gathered using campaigns())
957
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
958
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
959
+ * @return array array containing the total records matched and the specific records for this page
960
+ * @returnf int total the total number of records matched
961
+ * @returnf array data the actual opens data, including:
962
+ string email Email address that opened the campaign
963
+ int open_count Total number of times the campaign was opened by this email address
964
+ */
965
+ function campaignOpenedAIM($cid, $start=0, $limit=1000) {
966
+ $params = array();
967
+ $params["cid"] = $cid;
968
+ $params["start"] = $start;
969
+ $params["limit"] = $limit;
970
+ return $this->callServer("campaignOpenedAIM", $params);
971
+ }
972
+
973
+ /**
974
+ * Retrieve the list of email addresses that did not open a given campaign
975
+ *
976
+ * @section Campaign Report Data
977
+ *
978
+ * @param string $cid the campaign id to get no opens for (can be gathered using campaigns())
979
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
980
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
981
+ * @return array array containing the total records matched and the specific records for this page
982
+ * @returnf int total the total number of records matched
983
+ * @returnf array data the email addresses that did not open the campaign
984
+ string email Email address that opened the campaign
985
+ */
986
+ function campaignNotOpenedAIM($cid, $start=0, $limit=1000) {
987
+ $params = array();
988
+ $params["cid"] = $cid;
989
+ $params["start"] = $start;
990
+ $params["limit"] = $limit;
991
+ return $this->callServer("campaignNotOpenedAIM", $params);
992
+ }
993
+
994
+ /**
995
+ * Return the list of email addresses that clicked on a given url, and how many times they clicked
996
+ *
997
+ * @section Campaign Report Data
998
+ *
999
+ * @param string $cid the campaign id to get click stats for (can be gathered using campaigns())
1000
+ * @param string $url the URL of the link that was clicked on
1001
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1002
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
1003
+ * @return array array containing the total records matched and the specific records for this page
1004
+ * @returnf int total the total number of records matched
1005
+ * @returnf array data the email addresses that did not open the campaign
1006
+ string email Email address that opened the campaign
1007
+ int clicks Total number of times the URL was clicked on by this email address
1008
+ */
1009
+ function campaignClickDetailAIM($cid, $url, $start=0, $limit=1000) {
1010
+ $params = array();
1011
+ $params["cid"] = $cid;
1012
+ $params["url"] = $url;
1013
+ $params["start"] = $start;
1014
+ $params["limit"] = $limit;
1015
+ return $this->callServer("campaignClickDetailAIM", $params);
1016
+ }
1017
+
1018
+ /**
1019
+ * Given a campaign and email address, return the entire click and open history with timestamps, ordered by time
1020
+ *
1021
+ * @section Campaign Report Data
1022
+ *
1023
+ * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1024
+ * @param array $email_address an array of up to 50 email addresses to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns. For backwards compatibility, if a string is passed, it will be treated as an array with a single element (will not work with XML-RPC).
1025
+ * @return array an array with the keys listed in Returned Fields below
1026
+ * @returnf int success the number of email address records found
1027
+ * @returnf int error the number of email address records which could not be found
1028
+ * @returnf array data arrays containing the actions (opens and clicks) that the email took, with timestamps
1029
+ string action The action taken (open or click)
1030
+ string timestamp Time the action occurred
1031
+ string url For clicks, the URL that was clicked
1032
+ */
1033
+ function campaignEmailStatsAIM($cid, $email_address) {
1034
+ $params = array();
1035
+ $params["cid"] = $cid;
1036
+ $params["email_address"] = $email_address;
1037
+ return $this->callServer("campaignEmailStatsAIM", $params);
1038
+ }
1039
+
1040
+ /**
1041
+ * Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
1042
+ * for every user a campaign was delivered to.
1043
+ *
1044
+ * @section Campaign Report Data
1045
+ * @example mcapi_campaignEmailStatsAIMAll.php
1046
+ *
1047
+ * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1048
+ * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1049
+ * @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 1000
1050
+ * @return array Array containing a total record count and data including the actions (opens and clicks) for each email, with timestamps
1051
+ * @returnf int total the total number of records
1052
+ * @returnf array data each record with their details:
1053
+ string action The action taken (open or click)
1054
+ string timestamp Time the action occurred
1055
+ string url For clicks, the URL that was clicked
1056
+ */
1057
+ function campaignEmailStatsAIMAll($cid, $start=0, $limit=100) {
1058
+ $params = array();
1059
+ $params["cid"] = $cid;
1060
+ $params["start"] = $start;
1061
+ $params["limit"] = $limit;
1062
+ return $this->callServer("campaignEmailStatsAIMAll", $params);
1063
+ }
1064
+
1065
+ /**
1066
+ * Attach Ecommerce Order Information to a Campaign. This will generall be used by ecommerce package plugins
1067
+ * <a href="/plugins/ecomm360.phtml">that we provide</a> or by 3rd part system developers.
1068
+ * @section Campaign Related
1069
+ *
1070
+ * @param array $order an array of information pertaining to the order that has completed. Use the following keys:
1071
+ string id the Order Id
1072
+ string campaign_id the Campaign Id to track this order with (see the "mc_cid" query string variable a campaign passes)
1073
+ string email_id the Email Id of the subscriber we should attach this order to (see the "mc_eid" query string variable a campaign passes)
1074
+ double total The Order Total (ie, the full amount the customer ends up paying)
1075
+ string order_date optional the date of the order - if this is not provided, we will default the date to now
1076
+ double shipping optional the total paid for Shipping Fees
1077
+ double tax optional the total tax paid
1078
+ string store_id a unique id for the store sending the order in (20 bytes max)
1079
+ string store_name optional a "nice" name for the store - typically the base web address (ie, "store.mailchimp.com"). We will automatically update this if it changes (based on store_id)
1080
+ string plugin_id the MailChimp assigned Plugin Id. Get yours by <a href="/register.php">registering here</a>
1081
+ array items the individual line items for an order using these keys:
1082
+ <div style="padding-left:30px"><table><tr><td colspan=*>
1083
+ int line_num optional the line number of the item on the order. We will generate these if they are not passed
1084
+ int product_id the store's internal Id for the product. Lines that do no contain this will be skipped
1085
+ string product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
1086
+ int category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
1087
+ string category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
1088
+ double qty the quantity of the item ordered
1089
+ double cost the cost of a single item (ie, not the extended cost of the line)
1090
+ </td></tr></table></div>
1091
+ * @return bool true if the data is saved, otherwise an error is thrown.
1092
+ */
1093
+ function campaignEcommOrderAdd($order) {
1094
+ $params = array();
1095
+ $params["order"] = $order;
1096
+ return $this->callServer("campaignEcommOrderAdd", $params);
1097
+ }
1098
+
1099
+ /**
1100
+ * Retrieve all of the lists defined for your user account
1101
+ *
1102
+ * @section List Related
1103
+ * @example mcapi_lists.php
1104
+ * @example xml-rpc_lists.php
1105
+ *
1106
+ * @param array $filters a hash of filters to apply to this query - all are optional:
1107
+ string list_id optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching
1108
+ string list_name optional - only lists that match this name
1109
+ string from_name optional - only lists that have a default from name matching this
1110
+ string from_email optional - only lists that have a default from email matching this
1111
+ string from_subject optional - only lists that have a default from email matching this
1112
+ string created_before optional - only show lists that were created before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
1113
+ string created_after optional - only show lists that were created since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
1114
+ boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true
1115
+ * @param int $start optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
1116
+ * @param int $limit optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)
1117
+ * @return array an array with keys listed in Returned Fields below
1118
+ * @returnf int total the total number of lists which matched the provided filters
1119
+ * @returnf array data the lists which matched the provided filters, including the following for
1120
+ string id The list id for this list. This will be used for all other list management functions.
1121
+ int web_id The list id used in our web app, allows you to create a link directly to it
1122
+ string name The name of the list.
1123
+ string date_created The date that this list was created.
1124
+ boolean email_type_option Whether or not the List supports multiple formats for emails or just HTML
1125
+ boolean use_awesomebar Whether or not campaigns for this list use the Awesome Bar in archives by default
1126
+ string default_from_name Default From Name for campaigns using this list
1127
+ string default_from_email Default From Email for campaigns using this list
1128
+ string default_subject Default Subject Line for campaigns using this list
1129
+ string default_language Default Language for this list's forms
1130
+ int list_rating An auto-generated activity score for the list (0 - 5)
1131
+ array stats various stats and counts for the list
1132
+ int member_count The number of active members in the given list.
1133