Mailchimp_Lists

The Mailchimp Subscription Form Mailchimp Lists class.

Defined (1)

The class is defined in the following location(s).

/classes/mailchimp/Mailchimp/Lists.php  
  1. class Mailchimp_Lists { 
  2. public function __construct(NM_Mailchimp $master) { 
  3. $this->master = $master; 
  4.  
  5. /** 
  6. * Get all email addresses that complained about a campaign sent to a list 
  7. * @param string $id 
  8. * @param int $start 
  9. * @param int $limit 
  10. * @param string $since 
  11. * @return associative_array the total of all reports and the specific reports reports this page 
  12. * - total int the total number of matching abuse reports 
  13. * - data array structs for the actual data for each reports, including: 
  14. * - date string date+time the abuse report was received and processed 
  15. * - email string the email address that reported abuse 
  16. * - campaign_id string the unique id for the campaign that report was made against 
  17. * - type string an internal type generally specifying the originating mail provider - may not be useful outside of filling report views 
  18. */ 
  19. public function abuseReports($id, $start=0, $limit=500, $since=null) { 
  20. $_params = array("id" => $id, "start" => $start, "limit" => $limit, "since" => $since); 
  21. return $this->master->call('lists/abuse-reports', $_params); 
  22.  
  23. /** 
  24. * Access up to the previous 180 days of daily detailed aggregated activity stats for a given list. Does not include AutoResponder activity. 
  25. * @param string $id 
  26. * @return array of structs containing daily values, each containing: 
  27. */ 
  28. public function activity($id) { 
  29. $_params = array("id" => $id); 
  30. return $this->master->call('lists/activity', $_params); 
  31.  
  32. /** 
  33. * Subscribe a batch of email addresses to a list at once. If you are using a serialized version of the API, we strongly suggest that you 
  34. only run this method as a POST request, and <em>not</em> a GET request. Maximum batch sizes vary based on the amount of data in each record,  
  35. though you should cap them at 5k - 10k records, depending on your experience. These calls are also long, so be sure you increase your timeout values. 
  36. * @param string $id 
  37. * @param array $batch 
  38. * - email associative_array a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we'll use the first we see in this same order. 
  39. * - email string an email address 
  40. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  41. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  42. * - email_type string for the email type option (html or text) 
  43. * - merge_vars associative_array data for the various list specific and special merge vars documented in lists/subscribe 
  44. * @param boolean $double_optin 
  45. * @param boolean $update_existing 
  46. * @param boolean $replace_interests 
  47. * @return associative_array struct of result counts and associated data 
  48. * - add_count int Number of email addresses that were successfully added 
  49. * - adds array array of structs for each add 
  50. * - email string the email address added 
  51. * - euid string the email unique id 
  52. * - leid string the list member's truly unique id 
  53. * - update_count int Number of email addresses that were successfully updated 
  54. * - updates array array of structs for each update 
  55. * - email string the email address added 
  56. * - euid string the email unique id 
  57. * - leid string the list member's truly unique id 
  58. * - error_count int Number of email addresses that failed during addition/updating 
  59. * - errors array array of error structs including: 
  60. * - email string whatever was passed in the batch record's email parameter 
  61. * - email string the email address added 
  62. * - euid string the email unique id 
  63. * - leid string the list member's truly unique id 
  64. * - code int the error code 
  65. * - error string the full error message 
  66. * - row associative_array the row from the batch that caused the error 
  67. */ 
  68. public function batchSubscribe($id, $batch, $double_optin=true, $update_existing=false, $replace_interests=true) { 
  69. $_params = array("id" => $id, "batch" => $batch, "double_optin" => $double_optin, "update_existing" => $update_existing, "replace_interests" => $replace_interests); 
  70. return $this->master->call('lists/batch-subscribe', $_params); 
  71.  
  72. /** 
  73. * Unsubscribe a batch of email addresses from a list 
  74. * @param string $id 
  75. * @param array $batch 
  76. * - email string an email address 
  77. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  78. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  79. * @param boolean $delete_member 
  80. * @param boolean $send_goodbye 
  81. * @param boolean $send_notify 
  82. * @return array Array of structs containing results and any errors that occurred 
  83. * - success_count int Number of email addresses that were successfully removed 
  84. * - error_count int Number of email addresses that failed during addition/updating 
  85. * - errors array array of error structs including: 
  86. * - email string whatever was passed in the batch record's email parameter 
  87. * - email string the email address added 
  88. * - euid string the email unique id 
  89. * - leid string the list member's truly unique id 
  90. * - code int the error code 
  91. * - error string the full error message 
  92. */ 
  93. public function batchUnsubscribe($id, $batch, $delete_member=false, $send_goodbye=true, $send_notify=false) { 
  94. $_params = array("id" => $id, "batch" => $batch, "delete_member" => $delete_member, "send_goodbye" => $send_goodbye, "send_notify" => $send_notify); 
  95. return $this->master->call('lists/batch-unsubscribe', $_params); 
  96.  
  97. /** 
  98. * Retrieve the clients that the list's subscribers have been tagged as being used based on user agents seen. Made possible by <a href="http://user-agent-string.info" target="_blank">user-agent-string.info</a> 
  99. * @param string $id 
  100. * @return associative_array the desktop and mobile user agents in use on the list 
  101. * - desktop associative_array desktop user agents and percentages 
  102. * - penetration double the percent of desktop clients in use 
  103. * - clients array array of structs for each client including: 
  104. * - client string the common name for the client 
  105. * - icon string a url to an image representing this client 
  106. * - percent string percent of list using the client 
  107. * - members string total members using the client 
  108. * - mobile associative_array mobile user agents and percentages 
  109. * - penetration double the percent of mobile clients in use 
  110. * - clients array array of structs for each client including: 
  111. * - client string the common name for the client 
  112. * - icon string a url to an image representing this client 
  113. * - percent string percent of list using the client 
  114. * - members string total members using the client 
  115. */ 
  116. public function clients($id) { 
  117. $_params = array("id" => $id); 
  118. return $this->master->call('lists/clients', $_params); 
  119.  
  120. /** 
  121. * Access the Growth History by Month in aggregate or for a given list. 
  122. * @param string $id 
  123. * @return array array of structs containing months and growth data 
  124. * - month string The Year and Month in question using YYYY-MM format 
  125. * - existing int number of existing subscribers to start the month 
  126. * - imports int number of subscribers imported during the month 
  127. * - optins int number of subscribers who opted-in during the month 
  128. */ 
  129. public function growthHistory($id=null) { 
  130. $_params = array("id" => $id); 
  131. return $this->master->call('lists/growth-history', $_params); 
  132.  
  133. /** 
  134. * Get the list of interest groupings for a given list, including the label, form information, and included groups for each 
  135. * @param string $id 
  136. * @param bool $counts 
  137. * @return array array of structs of the interest groupings for the list 
  138. * - id int The id for the Grouping 
  139. * - name string Name for the Interest groups 
  140. * - form_field string Gives the type of interest group: checkbox, radio, select 
  141. * - groups array Array structs of the grouping options (interest groups) including: 
  142. * - bit string the bit value - not really anything to be done with this 
  143. * - name string the name of the group 
  144. * - display_order string the display order of the group, if set 
  145. * - subscribers int total number of subscribers who have this group if "counts" is true. otherwise empty 
  146. */ 
  147. public function interestGroupings($id, $counts=false) { 
  148. $_params = array("id" => $id, "counts" => $counts); 
  149. return $this->master->call('lists/interest-groupings', $_params); 
  150.  
  151. /** 
  152. * Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first 
  153. group will automatically turn them on. 
  154. * @param string $id 
  155. * @param string $group_name 
  156. * @param int $grouping_id 
  157. * @return associative_array with a single entry: 
  158. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  159. */ 
  160. public function interestGroupAdd($id, $group_name, $grouping_id=null) { 
  161. $_params = array("id" => $id, "group_name" => $group_name, "grouping_id" => $grouping_id); 
  162. return $this->master->call('lists/interest-group-add', $_params); 
  163.  
  164. /** 
  165. * Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off. 
  166. * @param string $id 
  167. * @param string $group_name 
  168. * @param int $grouping_id 
  169. * @return associative_array with a single entry: 
  170. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  171. */ 
  172. public function interestGroupDel($id, $group_name, $grouping_id=null) { 
  173. $_params = array("id" => $id, "group_name" => $group_name, "grouping_id" => $grouping_id); 
  174. return $this->master->call('lists/interest-group-del', $_params); 
  175.  
  176. /** 
  177. * Change the name of an Interest Group 
  178. * @param string $id 
  179. * @param string $old_name 
  180. * @param string $new_name 
  181. * @param int $grouping_id 
  182. * @return associative_array with a single entry: 
  183. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  184. */ 
  185. public function interestGroupUpdate($id, $old_name, $new_name, $grouping_id=null) { 
  186. $_params = array("id" => $id, "old_name" => $old_name, "new_name" => $new_name, "grouping_id" => $grouping_id); 
  187. return $this->master->call('lists/interest-group-update', $_params); 
  188.  
  189. /** 
  190. * Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first 
  191. grouping will automatically turn them on. 
  192. * @param string $id 
  193. * @param string $name 
  194. * @param string $type 
  195. * @param array $groups 
  196. * @return associative_array with a single entry: 
  197. * - id int the new grouping id if the request succeeds, otherwise an error will be thrown 
  198. */ 
  199. public function interestGroupingAdd($id, $name, $type, $groups) { 
  200. $_params = array("id" => $id, "name" => $name, "type" => $type, "groups" => $groups); 
  201. return $this->master->call('lists/interest-grouping-add', $_params); 
  202.  
  203. /** 
  204. * Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members 
  205. * @param int $grouping_id 
  206. * @return associative_array with a single entry: 
  207. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  208. */ 
  209. public function interestGroupingDel($grouping_id) { 
  210. $_params = array("grouping_id" => $grouping_id); 
  211. return $this->master->call('lists/interest-grouping-del', $_params); 
  212.  
  213. /** 
  214. * Update an existing Interest Grouping 
  215. * @param int $grouping_id 
  216. * @param string $name 
  217. * @param string $value 
  218. * @return associative_array with a single entry: 
  219. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  220. */ 
  221. public function interestGroupingUpdate($grouping_id, $name, $value) { 
  222. $_params = array("grouping_id" => $grouping_id, "name" => $name, "value" => $value); 
  223. return $this->master->call('lists/interest-grouping-update', $_params); 
  224.  
  225. /** 
  226. * Retrieve the locations (countries) that the list's subscribers have been tagged to based on geocoding their IP address 
  227. * @param string $id 
  228. * @return array array of locations 
  229. * - country string the country name 
  230. * - cc string the ISO 3166 2 digit country code 
  231. * - percent double the percent of subscribers in the country 
  232. * - total double the total number of subscribers in the country 
  233. */ 
  234. public function locations($id) { 
  235. $_params = array("id" => $id); 
  236. return $this->master->call('lists/locations', $_params); 
  237.  
  238. /** 
  239. * Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.) 
  240. * @param string $id 
  241. * @param array $emails 
  242. * - email string an email address - for new subscribers obviously this should be used 
  243. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  244. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  245. * @return associative_array of data and success/error counts 
  246. * - success_count int the number of subscribers successfully found on the list 
  247. * - error_count int the number of subscribers who were not found on the list 
  248. * - errors array array of error structs including: 
  249. * - email string whatever was passed in the email parameter 
  250. * - email string the email address added 
  251. * - euid string the email unique id 
  252. * - leid string the list member's truly unique id 
  253. * - error string the error message 
  254. * - code string the error code 
  255. * - data array an array of structs where each activity record has: 
  256. * - email string whatever was passed in the email parameter 
  257. * - email string the email address added 
  258. * - euid string the email unique id 
  259. * - leid string the list member's truly unique id 
  260. * - activity array an array of structs containing the activity, including: 
  261. * - action string The action name, one of: open, click, bounce, unsub, abuse, sent, queued, ecomm, mandrill_send, mandrill_hard_bounce, mandrill_soft_bounce, mandrill_open, mandrill_click, mandrill_spam, mandrill_unsub, mandrill_reject 
  262. * - timestamp string The date+time of the action (GMT) 
  263. * - url string For click actions, the url clicked, otherwise this is empty 
  264. * - type string If there's extra bounce, unsub, etc data it will show up here. 
  265. * - campaign_id string The campaign id the action was related to, if it exists - otherwise empty (ie, direct unsub from list) 
  266. * - campaign_data associative_array If not deleted, the campaigns/list data for the campaign 
  267. */ 
  268. public function memberActivity($id, $emails) { 
  269. $_params = array("id" => $id, "emails" => $emails); 
  270. return $this->master->call('lists/member-activity', $_params); 
  271.  
  272. /** 
  273. * Get all the information for particular members of a list 
  274. * @param string $id 
  275. * @param array $emails 
  276. * - email string an email address - for new subscribers obviously this should be used 
  277. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  278. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  279. * @return associative_array of data and success/error counts 
  280. * - success_count int the number of subscribers successfully found on the list 
  281. * - error_count int the number of subscribers who were not found on the list 
  282. * - errors array array of error structs including: 
  283. * - email associative_array whatever was passed in the email parameter 
  284. * - email string the email address added 
  285. * - euid string the email unique id 
  286. * - leid string the list member's truly unique id 
  287. * - error string the error message 
  288. * - data array array of structs for each valid list member 
  289. * - id string The unique id (euid) for this email address on an account 
  290. * - email string The email address associated with this record 
  291. * - email_type string The type of emails this customer asked to get: html or text 
  292. * - merges associative_array a struct containing a key for each merge tags and the data for those tags for this email address, plus: 
  293. * - GROUPINGS array if Interest groupings are enabled, this will exist with structs for each grouping: 
  294. * - id int the grouping id 
  295. * - name string the interest group name 
  296. * - groups array structs for each group in the grouping 
  297. * - name string the group name 
  298. * - interested bool whether the member has this group selected 
  299. * - status string The subscription status for this email address, either pending, subscribed, unsubscribed, or cleaned 
  300. * - ip_signup string IP Address this address signed up from. this may be blank if single optin is used. 
  301. * - timestamp_signup string The date+time the double optin was initiated. this may be blank if single optin is used. 
  302. * - ip_opt string IP Address this address opted in from. 
  303. * - timestamp_opt string The date+time the optin completed 
  304. * - member_rating int the rating of the subscriber. this will be 1 - 5 as described <a href="http://eepurl.com/f-2P" target="_blank">here</a> 
  305. * - campaign_id string If the user is unsubscribed and they unsubscribed from a specific campaign, that campaign_id will be listed, otherwise this is not returned. 
  306. * - lists array An array of structs for the other lists this member belongs to 
  307. * - id string the list id 
  308. * - status string the members status on that list 
  309. * - timestamp string The date+time this email address entered it's current status 
  310. * - info_changed string The last time this record was changed. If the record is old enough, this may be blank. 
  311. * - web_id int The Member id used in our web app, allows you to create a link directly to it 
  312. * - leid int The Member id used in our web app, allows you to create a link directly to it 
  313. * - list_id string The list id the for the member record being returned 
  314. * - list_name string The list name the for the member record being returned 
  315. * - language string if set/detected, a language code from <a href="http://kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code" target="_blank">here</a> 
  316. * - is_gmonkey bool Whether the member is a <a href="http://mailchimp.com/features/golden-monkeys/" target="_blank">Golden Monkey</a> or not. 
  317. * - geo associative_array the geographic information if we have it. including: 
  318. * - latitude string the latitude 
  319. * - longitude string the longitude 
  320. * - gmtoff string GMT offset 
  321. * - dstoff string GMT offset during daylight savings (if DST not observered, will be same as gmtoff) 
  322. * - timezone string the timezone we've place them in 
  323. * - cc string 2 digit ISO-3166 country code 
  324. * - region string generally state, province, or similar 
  325. * - clients associative_array the client we've tracked the address as using with two keys: 
  326. * - name string the common name of the client 
  327. * - icon_url string a url representing a path to an icon representing this client 
  328. * - static_segments array structs for each static segments the member is a part of including: 
  329. * - id int the segment id 
  330. * - name string the name given to the segment 
  331. * - added string the date the member was added 
  332. * - notes array structs for each note entered for this member. For each note: 
  333. * - id int the note id 
  334. * - note string the text entered 
  335. * - created string the date the note was created 
  336. * - updated string the date the note was last updated 
  337. * - created_by_name string the name of the user who created the note. this can change as users update their profile. 
  338. */ 
  339. public function memberInfo($id, $emails) { 
  340. $_params = array("id" => $id, "emails" => $emails); 
  341. return $this->master->call('lists/member-info', $_params); 
  342.  
  343. /** 
  344. * Get all of the list members for a list that are of a particular status and potentially matching a segment. this will cause locking, so don't run multiples at once. Are you trying to get a dump including lots of merge 
  345. data or specific members of a list? If so, checkout the <a href="/export/1.0/list.func.php">List Export API</a> 
  346. * @param string $id 
  347. * @param string $status 
  348. * @param associative_array $opts 
  349. * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0) 
  350. * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100 
  351. * - sort_field string optional the data field to sort by - mergeX (1-30), your custom merge tags, "email", "rating", "last_update_time", or "optin_time" - invalid fields will be ignored 
  352. * - sort_dir string optional the direct - ASC or DESC. defaults to ASC (case insensitive) 
  353. * - segment associative_array a properly formatted segment that works with campaigns/segment-test 
  354. * @return associative_array of the total records matched and limited list member data for this page 
  355. * - total int the total matching records 
  356. * - data array structs for each member as returned by member-info 
  357. */ 
  358. public function members($id, $status='subscribed', $opts=array()) { 
  359. $_params = array("id" => $id, "status" => $status, "opts" => $opts); 
  360. return $this->master->call('lists/members', $_params); 
  361.  
  362. /** 
  363. * Add a new merge tag to a given list 
  364. * @param string $id 
  365. * @param string $tag 
  366. * @param string $name 
  367. * @param associative_array $options 
  368. * - field_type string optional one of: text, number, radio, dropdown, date, address, phone, url, imageurl, zip, birthday - defaults to text 
  369. * - req boolean optional indicates whether the field is required - defaults to false 
  370. * - public boolean optional indicates whether the field is displayed in public - defaults to true 
  371. * - show boolean optional indicates whether the field is displayed in the app's list member view - defaults to true 
  372. * - order int The order this merge tag should be displayed in - this will cause existing values to be reset so this fits 
  373. * - default_value string optional the default value for the field. See lists/subscribe() for formatting info. Defaults to blank - max 255 bytes 
  374. * - helptext string optional the help text to be used with some newer forms. Defaults to blank - max 255 bytes 
  375. * - choices array optional kind of - an array of strings to use as the choices for radio and dropdown type fields 
  376. * - dateformat string optional only valid for birthday and date fields. For birthday type, must be "MM/DD" (default) or "DD/MM". For date type, must be "MM/DD/YYYY" (default) or "DD/MM/YYYY". Any other values will be converted to the default. 
  377. * - phoneformat string optional "US" is the default - any other value will cause them to be unformatted (international) 
  378. * - defaultcountry string optional the <a href="http://www.iso.org/iso/english_country_names_and_code_elements" target="_blank">ISO 3166 2 digit character code</a> for the default country. Defaults to "US". Anything unrecognized will be converted to the default. 
  379. * @return associative_array the full data for the new merge var, just like merge-vars returns 
  380. * - name string Name/description of the merge field 
  381. * - req bool Denotes whether the field is required (true) or not (false) 
  382. * - field_type string The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl 
  383. * - public bool Whether or not this field is visible to list subscribers 
  384. * - show bool Whether the field is displayed in thelist dashboard 
  385. * - order string The order this field displays in on forms 
  386. * - default string The default value for this field 
  387. * - helptext string The helptext for this field 
  388. * - size string The width of the field to be used 
  389. * - tag string The merge tag that's used for forms and lists/subscribe() and lists/update-member() 
  390. * - choices array the options available for radio and dropdown field types 
  391. * - id int an unchanging id for the merge var 
  392. */ 
  393. public function mergeVarAdd($id, $tag, $name, $options=array()) { 
  394. $_params = array("id" => $id, "tag" => $tag, "name" => $name, "options" => $options); 
  395. return $this->master->call('lists/merge-var-add', $_params); 
  396.  
  397. /** 
  398. * Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well! 
  399. Note that on large lists this method may seem a bit slower than calls you typically make. 
  400. * @param string $id 
  401. * @param string $tag 
  402. * @return associative_array with a single entry: 
  403. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  404. */ 
  405. public function mergeVarDel($id, $tag) { 
  406. $_params = array("id" => $id, "tag" => $tag); 
  407. return $this->master->call('lists/merge-var-del', $_params); 
  408.  
  409. /** 
  410. * Completely resets all data stored in a merge var on a list. All data is removed and this action can not be undone. 
  411. * @param string $id 
  412. * @param string $tag 
  413. * @return associative_array with a single entry: 
  414. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  415. */ 
  416. public function mergeVarReset($id, $tag) { 
  417. $_params = array("id" => $id, "tag" => $tag); 
  418. return $this->master->call('lists/merge-var-reset', $_params); 
  419.  
  420. /** 
  421. * Sets a particular merge var to the specified value for every list member. Only merge var ids 1 - 30 may be modified this way. this is generally a dirty method 
  422. unless you're fixing data since you should probably be using default_values and/or conditional content. as with lists/merge-var-reset(), this can not be undone. 
  423. * @param string $id 
  424. * @param string $tag 
  425. * @param string $value 
  426. * @return associative_array with a single entry: 
  427. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  428. */ 
  429. public function mergeVarSet($id, $tag, $value) { 
  430. $_params = array("id" => $id, "tag" => $tag, "value" => $value); 
  431. return $this->master->call('lists/merge-var-set', $_params); 
  432.  
  433. /** 
  434. * Update most parameters for a merge tag on a given list. You cannot currently change the merge type 
  435. * @param string $id 
  436. * @param string $tag 
  437. * @param associative_array $options 
  438. * @return associative_array the full data for the new merge var, just like merge-vars returns 
  439. * - name string Name/description of the merge field 
  440. * - req bool Denotes whether the field is required (true) or not (false) 
  441. * - field_type string The "data type" of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl 
  442. * - public bool Whether or not this field is visible to list subscribers 
  443. * - show bool Whether the field is displayed in thelist dashboard 
  444. * - order string The order this field to displays in on forms 
  445. * - default string The default value for this field 
  446. * - helptext string The helptext for this field 
  447. * - size string The width of the field to be used 
  448. * - tag string The merge tag that's used for forms and lists/subscribe() and lists/update-member() 
  449. * - choices array the options available for radio and dropdown field types 
  450. * - id int an unchanging id for the merge var 
  451. */ 
  452. public function mergeVarUpdate($id, $tag, $options) { 
  453. $_params = array("id" => $id, "tag" => $tag, "options" => $options); 
  454. return $this->master->call('lists/merge-var-update', $_params); 
  455.  
  456. /** 
  457. * Get the list of merge tags for a given list, including their name, tag, and required setting 
  458. * @param array $id 
  459. * @return associative_array of data and success/error counts 
  460. * - success_count int the number of subscribers successfully found on the list 
  461. * - error_count int the number of subscribers who were not found on the list 
  462. * - data array of structs for the merge tags on each list 
  463. * - id string the list id 
  464. * - name string the list name 
  465. * - merge_vars array of structs for each merge var 
  466. * - name string Name of the merge field 
  467. * - req bool Denotes whether the field is required (true) or not (false) 
  468. * - field_type string The "data type" of this merge var. One of the options accepted by field_type in lists/merge-var-add 
  469. * - public bool Whether or not this field is visible to list subscribers 
  470. * - show bool Whether the list owner has this field displayed on their list dashboard 
  471. * - order string The order the list owner has set this field to display in 
  472. * - default string The default value the list owner has set for this field 
  473. * - helptext string The helptext for this field 
  474. * - size string The width of the field to be used 
  475. * - tag string The merge tag that's used for forms and lists/subscribe() and listUpdateMember() 
  476. * - choices array For radio and dropdown field types, an array of the options available 
  477. * - id int an unchanging id for the merge var 
  478. * - errors array of error structs 
  479. * - id string the passed list id that failed 
  480. * - code int the resulting error code 
  481. * - msg string the resulting error message 
  482. */ 
  483. public function mergeVars($id) { 
  484. $_params = array("id" => $id); 
  485. return $this->master->call('lists/merge-vars', $_params); 
  486.  
  487. /** 
  488. * Retrieve all of Segments for a list. 
  489. * @param string $id 
  490. * @param string $type 
  491. * @return associative_array with 2 keys: 
  492. * - static array of structs with data for each segment 
  493. * - id int the id of the segment 
  494. * - name string the name for the segment 
  495. * - created_date string the date+time the segment was created 
  496. * - last_update string the date+time the segment was last updated (add or del) 
  497. * - last_reset string the date+time the segment was last reset (ie had all members cleared from it) 
  498. * - saved array of structs with data for each segment 
  499. * - id int the id of the segment 
  500. * - name string the name for the segment 
  501. * - segment_opts string same match+conditions struct typically used 
  502. * - segment_text string a textual description of the segment match/conditions 
  503. * - created_date string the date+time the segment was created 
  504. * - last_update string the date+time the segment was last updated (add or del) 
  505. */ 
  506. public function segments($id, $type=null) { 
  507. $_params = array("id" => $id, "type" => $type); 
  508. return $this->master->call('lists/segments', $_params); 
  509.  
  510. /** 
  511. * Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied 
  512. to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. 
  513. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation 
  514. options), though performance may degrade at that point. Saved Segments (called "auto-updating" in the app) are essentially just the match+conditions typically 
  515. used. 
  516. * @param string $id 
  517. * @param associative_array $opts 
  518. * - type string either "static" or "saved" 
  519. * - name string a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error 
  520. * - segment_opts associative_array for "saved" only, the standard segment match+conditions, just like campaigns/segment-test 
  521. * - match string "any" or "all" 
  522. * - conditions array structs for each condition, just like campaigns/segment-test 
  523. * @return associative_array with a single entry: 
  524. * - id int the id of the new segment, otherwise an error will be thrown. 
  525. */ 
  526. public function segmentAdd($id, $opts) { 
  527. $_params = array("id" => $id, "opts" => $opts); 
  528. return $this->master->call('lists/segment-add', $_params); 
  529.  
  530. /** 
  531. * Delete a segment. Note that this will, of course, remove any member affiliations with any static segments deleted 
  532. * @param string $id 
  533. * @param int $seg_id 
  534. * @return associative_array with a single entry: 
  535. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  536. */ 
  537. public function segmentDel($id, $seg_id) { 
  538. $_params = array("id" => $id, "seg_id" => $seg_id); 
  539. return $this->master->call('lists/segment-del', $_params); 
  540.  
  541. /** 
  542. * Allows one to test their segmentation rules before creating a campaign using them - this is no different from campaigns/segment-test() and will eventually replace it. 
  543. For the time being, the crazy segmenting condition documentation will continue to live over there. 
  544. * @param string $list_id 
  545. * @param associative_array $options 
  546. * @return associative_array with a single entry: 
  547. * - total int The total number of subscribers matching your segmentation options 
  548. */ 
  549. public function segmentTest($list_id, $options) { 
  550. $_params = array("list_id" => $list_id, "options" => $options); 
  551. return $this->master->call('lists/segment-test', $_params); 
  552.  
  553. /** 
  554. * Update an existing segment. The list and type can not be changed. 
  555. * @param string $id 
  556. * @param int $seg_id 
  557. * @param associative_array $opts 
  558. * - name string a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error 
  559. * - segment_opts associative_array for "saved" only, the standard segment match+conditions, just like campaigns/segment-test 
  560. * - match string "any" or "all" 
  561. * - conditions array structs for each condition, just like campaigns/segment-test 
  562. * @return associative_array with a single entry: 
  563. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  564. */ 
  565. public function segmentUpdate($id, $seg_id, $opts) { 
  566. $_params = array("id" => $id, "seg_id" => $seg_id, "opts" => $opts); 
  567. return $this->master->call('lists/segment-update', $_params); 
  568.  
  569. /** 
  570. * Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied 
  571. to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. 
  572. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation 
  573. options), though performance may degrade at that point. 
  574. * @param string $id 
  575. * @param string $name 
  576. * @return associative_array with a single entry: 
  577. * - id int the id of the new segment, otherwise an error will be thrown. 
  578. */ 
  579. public function staticSegmentAdd($id, $name) { 
  580. $_params = array("id" => $id, "name" => $name); 
  581. return $this->master->call('lists/static-segment-add', $_params); 
  582.  
  583. /** 
  584. * Delete a static segment. Note that this will, of course, remove any member affiliations with the segment 
  585. * @param string $id 
  586. * @param int $seg_id 
  587. * @return associative_array with a single entry: 
  588. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  589. */ 
  590. public function staticSegmentDel($id, $seg_id) { 
  591. $_params = array("id" => $id, "seg_id" => $seg_id); 
  592. return $this->master->call('lists/static-segment-del', $_params); 
  593.  
  594. /** 
  595. * Add list members to a static segment. It is suggested that you limit batch size to no more than 10, 000 addresses per call. Email addresses must exist on the list 
  596. in order to be included - this <strong>will not</strong> subscribe them to the list! 
  597. * @param string $id 
  598. * @param int $seg_id 
  599. * @param array $batch 
  600. * - email string an email address 
  601. * - euid string the unique id for an email address (not list related) - the email "id" returned from lists/member-info(), Webhooks, Campaigns, etc. 
  602. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  603. * @return associative_array an array with the results of the operation 
  604. * - success_count int the total number of successful updates (will include members already in the segment) 
  605. * - error_count int the total number of errors 
  606. * - errors array structs for each error including: 
  607. * - email string whatever was passed in the email parameter 
  608. * - email string the email address added 
  609. * - euid string the email unique id 
  610. * - leid string the list member's truly unique id 
  611. * - code string the error code 
  612. * - error string the full error message 
  613. */ 
  614. public function staticSegmentMembersAdd($id, $seg_id, $batch) { 
  615. $_params = array("id" => $id, "seg_id" => $seg_id, "batch" => $batch); 
  616. return $this->master->call('lists/static-segment-members-add', $_params); 
  617.  
  618. /** 
  619. * Remove list members from a static segment. It is suggested that you limit batch size to no more than 10, 000 addresses per call. Email addresses must exist on the list 
  620. in order to be removed - this <strong>will not</strong> unsubscribe them from the list! 
  621. * @param string $id 
  622. * @param int $seg_id 
  623. * @param array $batch 
  624. * - email string an email address 
  625. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  626. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  627. * @return associative_array an array with the results of the operation 
  628. * - success_count int the total number of successful removals 
  629. * - error_count int the total number of unsuccessful removals 
  630. * - errors array structs for each error including: 
  631. * - email string whatever was passed in the email parameter 
  632. * - email string the email address added 
  633. * - euid string the email unique id 
  634. * - leid string the list member's truly unique id 
  635. * - code string the error code 
  636. * - error string the full error message 
  637. */ 
  638. public function staticSegmentMembersDel($id, $seg_id, $batch) { 
  639. $_params = array("id" => $id, "seg_id" => $seg_id, "batch" => $batch); 
  640. return $this->master->call('lists/static-segment-members-del', $_params); 
  641.  
  642. /** 
  643. * Resets a static segment - removes <strong>all</strong> members from the static segment. Note: does not actually affect list member data 
  644. * @param string $id 
  645. * @param int $seg_id 
  646. * @return associative_array with a single entry: 
  647. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  648. */ 
  649. public function staticSegmentReset($id, $seg_id) { 
  650. $_params = array("id" => $id, "seg_id" => $seg_id); 
  651. return $this->master->call('lists/static-segment-reset', $_params); 
  652.  
  653. /** 
  654. * Retrieve all of the Static Segments for a list. 
  655. * @param string $id 
  656. * @param boolean $get_counts 
  657. * @param int $start 
  658. * @param int $limit 
  659. * @return array an of structs with data for each static segment 
  660. * - id int the id of the segment 
  661. * - name string the name for the segment 
  662. * - member_count int the total number of subscribed members currently in a segment 
  663. * - created_date string the date+time the segment was created 
  664. * - last_update string the date+time the segment was last updated (add or del) 
  665. * - last_reset string the date+time the segment was last reset (ie had all members cleared from it) 
  666. */ 
  667. public function staticSegments($id, $get_counts=true, $start=0, $limit=null) { 
  668. $_params = array("id" => $id, "get_counts" => $get_counts, "start" => $start, "limit" => $limit); 
  669. return $this->master->call('lists/static-segments', $_params); 
  670.  
  671. /** 
  672. * 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! 
  673. * @param string $id 
  674. * @param associative_array $email 
  675. * - email string an email address - for new subscribers obviously this should be used 
  676. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  677. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  678. * @param associative_array $merge_vars 
  679. * - new-email string set this to change the email address. this is only respected on calls using update_existing or when passed to lists/update. 
  680. * - groupings array of Interest Grouping structs. Each should contain: 
  681. * - id int Grouping "id" from lists/interest-groupings (either this or name must be present) - this id takes precedence and can't change (unlike the name) 
  682. * - name string Grouping "name" from lists/interest-groupings (either this or id must be present) 
  683. * - groups array an array of valid group names for this grouping. 
  684. * - optin_ip string Set the Opt-in IP field. <em>Abusing this may cause your account to be suspended.</em> We do validate this and it must not be a private IP address. 
  685. * - optin_time string Set the Opt-in Time field. <em>Abusing this may cause your account to be suspended.</em> We do validate this and it must be a valid date. Use - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" 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> 
  686. * - mc_location associative_array Set the member's geographic location either by optin_ip or geo data. 
  687. * - latitude string use the specified latitude (longitude must exist for this to work) 
  688. * - longitude string use the specified longitude (latitude must exist for this to work) 
  689. * - anything string if this (or any other key exists here) we'll try to use the optin ip. NOTE - this will slow down each subscribe call a bit, especially for lat/lng pairs in sparsely populated areas. Currently our automated background processes can and will overwrite this based on opens and clicks. 
  690. * - mc_language string Set the member's language preference. Supported codes are fully case-sensitive and can be found <a href="http://kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code" target="_new">here</a>. 
  691. * - mc_notes array of structs for managing notes - it may contain: 
  692. * - note string the note to set. this is required unless you're deleting a note 
  693. * - id int the note id to operate on. not including this (or using an invalid id) causes a new note to be added 
  694. * - action string if the "id" key exists and is valid, an "update" key may be set to "append" (default), "prepend", "replace", or "delete" to handle how we should update existing notes. "delete", obviously, will only work with a valid "id" - passing that along with "note" and an invalid "id" is wrong and will be ignored. 
  695. * @param string $email_type 
  696. * @param bool $double_optin 
  697. * @param bool $update_existing 
  698. * @param bool $replace_interests 
  699. * @param bool $send_welcome 
  700. * @return associative_array the ids for this subscriber 
  701. * - email string the email address added 
  702. * - euid string the email unique id 
  703. * - leid string the list member's truly unique id 
  704. */ 
  705. public function subscribe($id, $email, $merge_vars=null, $email_type='html', $double_optin=true, $update_existing=false, $replace_interests=true, $send_welcome=false) { 
  706. $_params = array("id" => $id, "email" => $email, "merge_vars" => $merge_vars, "email_type" => $email_type, "double_optin" => $double_optin, "update_existing" => $update_existing, "replace_interests" => $replace_interests, "send_welcome" => $send_welcome); 
  707. return $this->master->call('lists/subscribe', $_params); 
  708.  
  709. /** 
  710. * Unsubscribe the given email address from the list 
  711. * @param string $id 
  712. * @param associative_array $email 
  713. * - email string an email address 
  714. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  715. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  716. * @param boolean $delete_member 
  717. * @param boolean $send_goodbye 
  718. * @param boolean $send_notify 
  719. * @return associative_array with a single entry: 
  720. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  721. */ 
  722. public function unsubscribe($id, $email, $delete_member=false, $send_goodbye=true, $send_notify=true) { 
  723. $_params = array("id" => $id, "email" => $email, "delete_member" => $delete_member, "send_goodbye" => $send_goodbye, "send_notify" => $send_notify); 
  724. return $this->master->call('lists/unsubscribe', $_params); 
  725.  
  726. /** 
  727. * Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users,  
  728. consider using lists/batch-subscribe() with the update_existing and possible replace_interests parameter. 
  729. * @param string $id 
  730. * @param associative_array $email 
  731. * - email string an email address 
  732. * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc. 
  733. * - leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes 
  734. * @param associative_array $merge_vars 
  735. * @param string $email_type 
  736. * @param boolean $replace_interests 
  737. * @return associative_array the ids for this subscriber 
  738. * - email string the email address added 
  739. * - euid string the email unique id 
  740. * - leid string the list member's truly unique id 
  741. */ 
  742. public function updateMember($id, $email, $merge_vars, $email_type='', $replace_interests=true) { 
  743. $_params = array("id" => $id, "email" => $email, "merge_vars" => $merge_vars, "email_type" => $email_type, "replace_interests" => $replace_interests); 
  744. return $this->master->call('lists/update-member', $_params); 
  745.  
  746. /** 
  747. * Add a new Webhook URL for the given list 
  748. * @param string $id 
  749. * @param string $url 
  750. * @param associative_array $actions 
  751. * - subscribe bool optional as subscribes occur, defaults to true 
  752. * - unsubscribe bool optional as subscribes occur, defaults to true 
  753. * - profile bool optional as profile updates occur, defaults to true 
  754. * - cleaned bool optional as emails are cleaned from the list, defaults to true 
  755. * - upemail bool optional when subscribers change their email address, defaults to true 
  756. * - campaign bool option when a campaign is sent or canceled, defaults to true 
  757. * @param associative_array $sources 
  758. * - user bool optional user/subscriber initiated actions, defaults to true 
  759. * - admin bool optional admin actions in our web app, defaults to true 
  760. * - api bool optional actions that happen via API calls, defaults to false 
  761. * @return associative_array with a single entry: 
  762. * - id int the id of the new webhook, otherwise an error will be thrown. 
  763. */ 
  764. public function webhookAdd($id, $url, $actions=array(), $sources=array()) { 
  765. $_params = array("id" => $id, "url" => $url, "actions" => $actions, "sources" => $sources); 
  766. return $this->master->call('lists/webhook-add', $_params); 
  767.  
  768. /** 
  769. * Delete an existing Webhook URL from a given list 
  770. * @param string $id 
  771. * @param string $url 
  772. * @return associative_array with a single entry: 
  773. * - complete bool whether the call worked. reallistically this will always be true as errors will be thrown otherwise. 
  774. */ 
  775. public function webhookDel($id, $url) { 
  776. $_params = array("id" => $id, "url" => $url); 
  777. return $this->master->call('lists/webhook-del', $_params); 
  778.  
  779. /** 
  780. * Return the Webhooks configured for the given list 
  781. * @param string $id 
  782. * @return array of structs for each webhook 
  783. * - url string the URL for this Webhook 
  784. * - actions associative_array the possible actions and whether they are enabled 
  785. * - subscribe bool triggered when subscribes happen 
  786. * - unsubscribe bool triggered when unsubscribes happen 
  787. * - profile bool triggered when profile updates happen 
  788. * - cleaned bool triggered when a subscriber is cleaned (bounced) from a list 
  789. * - upemail bool triggered when a subscriber's email address is changed 
  790. * - campaign bool triggered when a campaign is sent or canceled 
  791. * - sources associative_array the possible sources and whether they are enabled 
  792. * - user bool whether user/subscriber triggered actions are returned 
  793. * - admin bool whether admin (manual, in-app) triggered actions are returned 
  794. * - api bool whether api triggered actions are returned 
  795. */ 
  796. public function webhooks($id) { 
  797. $_params = array("id" => $id); 
  798. return $this->master->call('lists/webhooks', $_params); 
  799.  
  800. /** 
  801. * Retrieve all of the lists defined for your user account 
  802. * @param associative_array $filters 
  803. * - list_id string optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching 
  804. * - list_name string optional - only lists that match this name 
  805. * - from_name string optional - only lists that have a default from name matching this 
  806. * - from_email string optional - only lists that have a default from email matching this 
  807. * - from_subject string optional - only lists that have a default from email matching this 
  808. * - created_before string optional - only show lists that were created before this date+time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" 
  809. * - created_after string optional - only show lists that were created since this date+time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00" 
  810. * - exact boolean optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to false 
  811. * @param int $start 
  812. * @param int $limit 
  813. * @param string $sort_field 
  814. * @param string $sort_dir 
  815. * @return associative_array result of the operation including valid data and any errors 
  816. * - total int the total number of lists which matched the provided filters 
  817. * - data array structs for the lists which matched the provided filters, including the following 
  818. * - id string The list id for this list. this will be used for all other list management functions. 
  819. * - web_id int The list id used in our web app, allows you to create a link directly to it 
  820. * - name string The name of the list. 
  821. * - date_created string The date that this list was created. 
  822. * - email_type_option boolean Whether or not the List supports multiple formats for emails or just HTML 
  823. * - use_awesomebar boolean Whether or not campaigns for this list use the Awesome Bar in archives by default 
  824. * - default_from_name string Default From Name for campaigns using this list 
  825. * - default_from_email string Default From Email for campaigns using this list 
  826. * - default_subject string Default Subject Line for campaigns using this list 
  827. * - default_language string Default Language for this list's forms 
  828. * - list_rating double An auto-generated activity score for the list (0 - 5) 
  829. * - subscribe_url_short string Our eepurl shortened version of this list's subscribe form (will not change) 
  830. * - subscribe_url_long string The full version of this list's subscribe form (host will vary) 
  831. * - beamer_address string The email address to use for this list's <a href="http://kb.mailchimp.com/article/how-do-i-import-a-campaign-via-email-email-beamer/">Email Beamer</a> 
  832. * - visibility string Whether this list is Public (pub) or Private (prv). Used internally for projects like <a href="http://blog.mailchimp.com/introducing-wavelength/" target="_blank">Wavelength</a> 
  833. * - stats associative_array various stats and counts for the list - many of these are cached for at least 5 minutes 
  834. * - member_count double The number of active members in the given list. 
  835. * - unsubscribe_count double The number of members who have unsubscribed from the given list. 
  836. * - cleaned_count double The number of members cleaned from the given list. 
  837. * - member_count_since_send double The number of active members in the given list since the last campaign was sent 
  838. * - unsubscribe_count_since_send double The number of members who have unsubscribed from the given list since the last campaign was sent 
  839. * - cleaned_count_since_send double The number of members cleaned from the given list since the last campaign was sent 
  840. * - campaign_count double The number of campaigns in any status that use this list 
  841. * - grouping_count double The number of Interest Groupings for this list 
  842. * - group_count double The number of Interest Groups (regardless of grouping) for this list 
  843. * - merge_var_count double The number of merge vars for this list (not including the required EMAIL one) 
  844. * - avg_sub_rate double the average number of subscribe per month for the list (empty value if we haven't calculated this yet) 
  845. * - avg_unsub_rate double the average number of unsubscribe per month for the list (empty value if we haven't calculated this yet) 
  846. * - target_sub_rate double the target subscription rate for the list to keep it growing (empty value if we haven't calculated this yet) 
  847. * - open_rate double the average open rate per campaign for the list (empty value if we haven't calculated this yet) 
  848. * - click_rate double the average click rate per campaign for the list (empty value if we haven't calculated this yet) 
  849. * - modules array Any list specific modules installed for this list (example is SocialPro) 
  850. * - errors array structs of any errors found while loading lists - usually just from providing invalid list ids 
  851. * - param string the data that caused the failure 
  852. * - code int the error code 
  853. * - error string the error message 
  854. */ 
  855. public function getList($filters=array(), $start=0, $limit=25, $sort_field='created', $sort_dir='DESC') { 
  856. $_params = array("filters" => $filters, "start" => $start, "limit" => $limit, "sort_field" => $sort_field, "sort_dir" => $sort_dir); 
  857. return $this->master->call('lists/list', $_params); 
  858.