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