      1: <?php
      2:
      3: class Mailchimp_Helper {
      4:     public function __construct(Mailchimp $master) {
      5:         $this->master = $master;
      6:     }
      7:
      8:     /**
      9:      * Retrieve lots of account information including payments made, plan info, some account stats, installed modules,
     10: contact info, and more. No private information like Credit Card numbers is available.
     11:      * @param array $exclude
     12:      * @return associative_array containing the details for the account tied to this API Key
     13:      *     - username string The Account username
     14:      *     - user_id string The Account user unique id (for building some links)
     15:      *     - is_trial bool Whether the Account is in Trial mode (can only send campaigns to less than 100 emails)
     16:      *     - is_approved bool Whether the Account has been approved for purchases
     17:      *     - has_activated bool Whether the Account has been activated
     18:      *     - timezone string The timezone for the Account - default is "US/Eastern"
     19:      *     - plan_type string Plan Type - "monthly", "payasyougo", or "free"
     20:      *     - plan_low int <em>only for Monthly plans</em> - the lower tier for list size
     21:      *     - plan_high int <em>only for Monthly plans</em> - the upper tier for list size
     22:      *     - plan_start_date string <em>only for Monthly plans</em> - the start date for a monthly plan
     23:      *     - emails_left int <em>only for Free and Pay-as-you-go plans</em> emails credits left for the account
     24:      *     - pending_monthly bool Whether the account is finishing Pay As You Go credits before switching to a Monthly plan
     25:      *     - first_payment string date of first payment
     26:      *     - last_payment string date of most recent payment
     27:      *     - times_logged_in int total number of times the account has been logged into via the web
     28:      *     - last_login string date/time of last login via the web
     29:      *     - affiliate_link string Monkey Rewards link for our Affiliate program
     30:      *     - industry string the user's selected industry
     31:      *     - contact associative_array Contact details for the account
     32:      *         - fname string First Name
     33:      *         - lname string Last Name
     34:      *         - email string Email Address
     35:      *         - company string Company Name
     36:      *         - address1 string Address Line 1
     37:      *         - address2 string Address Line 2
     38:      *         - city string City
     39:      *         - state string State or Province
     40:      *         - zip string Zip or Postal Code
     41:      *         - country string Country name
     42:      *         - url string Website URL
     43:      *         - phone string Phone number
     44:      *         - fax string Fax number
     45:      *     - modules array a struct for each addon module installed in the account
     46:      *         - id string An internal module id
     47:      *         - name string The module name
     48:      *         - added string The date the module was added
     49:      *         - data associative_array Any extra data associated with this module as key=>value pairs
     50:      *     - orders array a struct for each order for the account
     51:      *         - order_id int The order id
     52:      *         - type string The order type - either "monthly" or "credits"
     53:      *         - amount double The order amount
     54:      *         - date string The order date
     55:      *         - credits_used double The total credits used
     56:      *     - rewards associative_array Rewards details for the account including credits & inspections earned, number of referrals, referral details, and rewards used
     57:      *         - referrals_this_month int the total number of referrals this month
     58:      *         - notify_on string whether or not we notify the user when rewards are earned
     59:      *         - notify_email string the email address address used for rewards notifications
     60:      *         - credits associative_array Email credits earned:
     61:      *             - this_month int credits earned this month
     62:      *             - total_earned int credits earned all time
     63:      *             - remaining int credits remaining
     64:      *         - inspections associative_array Inbox Inspections earned:
     65:      *             - this_month int credits earned this month
     66:      *             - total_earned int credits earned all time
     67:      *             - remaining int credits remaining
     68:      *         - referrals array a struct for each referral, including:
     69:      *             - name string the name of the account
     70:      *             - email string the email address associated with the account
     71:      *             - signup_date string the signup date for the account
     72:      *             - type string the source for the referral
     73:      *         - applied array a struct for each applied rewards, including:
     74:      *             - value int the number of credits user
     75:      *             - date string the date applied
     76:      *             - order_id int the order number credits were applied to
     77:      *             - order_desc string the order description
     78:      *     - integrations array a struct for each connected integrations that can be used with campaigns, including:
     79:      *         - id int an internal id for the integration
     80:      *         - name string the integration name
     81:      *         - list_id string either "_any_" when globally accessible or the list id it's valid for use against
     82:      *         - user_id string if applicable, the user id for the integrated system
     83:      *         - account string if applicable, the user/account name for the integrated system
     84:      *         - profiles array For Facebook, users/page that can be posted to.
     85:      *             - id string the user or page id
     86:      *             - name string the user or page name
     87:      *             - is_page bool whether this is a user or a page
     88:      */
     89:     public function accountDetails($exclude=array()) {
     90:         $_params = array("exclude" => $exclude);
     91:         return $this->master->call('helper/account-details', $_params);
     92:     }
     93:
     94:     /**
     95:      * Retrieve minimal data for all Campaigns a member was sent
     96:      * @param associative_array $email
     97:      *     - email string an email address
     98:      *     - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
     99:      *     - 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
    100:      * @param associative_array $options
    101:      *     - list_id string optional A list_id to limit the campaigns to
    102:      * @return array an array of structs containing campaign data for each matching campaign (ordered by send time ascending), including:
    103:      *     - id string the campaign unique id
    104:      *     - title string the campaign's title
    105:      *     - subject string the campaign's subject
    106:      *     - send_time string the time the campaign was sent
    107:      *     - type string the campaign type
    108:      */
    109:     public function campaignsForEmail($email, $options=null) {
    110:         $_params = array("email" => $email, "options" => $options);
    111:         return $this->master->call('helper/campaigns-for-email', $_params);
    112:     }
    113:
    114:     /**
    115:      * Return the current Chimp Chatter messages for an account.
    116:      * @return array An array of structs containing data for each chatter message
    117:      *     - message string The chatter message
    118:      *     - type string The type of the message - one of lists:new-subscriber, lists:unsubscribes, lists:profile-updates, campaigns:facebook-likes, campaigns:facebook-comments, campaigns:forward-to-friend, lists:imports, or campaigns:inbox-inspections
    119:      *     - url string a url into the web app that the message could link to, if applicable
    120:      *     - list_id string the list_id a message relates to, if applicable. Deleted lists will return -DELETED-
    121:      *     - campaign_id string the list_id a message relates to, if applicable. Deleted campaigns will return -DELETED-
    122:      *     - update_time string The date/time the message was last updated
    123:      */
    124:     public function chimpChatter() {
    125:         $_params = array();
    126:         return $this->master->call('helper/chimp-chatter', $_params);
    127:     }
    128:
    129:     /**
    130:      * Have HTML content auto-converted to a text-only format. You can send: plain HTML, an existing Campaign Id, or an existing Template Id. Note that this will <strong>not</strong> save anything to or update any of your lists, campaigns, or templates.
    131: It's also not just Lynx and is very fine tuned for our template layouts - your mileage may vary.
    132:      * @param string $type
    133:      * @param associative_array $content
    134:      *     - html string optional a single string value,
    135:      *     - cid string a valid Campaign Id
    136:      *     - user_template_id string the id of a user template
    137:      *     - base_template_id string the id of a built in base/basic template
    138:      *     - gallery_template_id string the id of a built in gallery template
    139:      *     - url string a valid & public URL to pull html content from
    140:      * @return associative_array the content pass in converted to text.
    141:      *     - text string the converted html
    142:      */
    143:     public function generateText($type, $content) {
    144:         $_params = array("type" => $type, "content" => $content);
    145:         return $this->master->call('helper/generate-text', $_params);
    146:     }
    147:
    148:     /**
    149:      * Send your HTML content to have the CSS inlined and optionally remove the original styles.
    150:      * @param string $html
    151:      * @param bool $strip_css
    152:      * @return associative_array with a "html" key
    153:      *     - html string Your HTML content with all CSS inlined, just like if we sent it.
    154:      */
    155:     public function inlineCss($html, $strip_css=false) {
    156:         $_params = array("html" => $html, "strip_css" => $strip_css);
    157:         return $this->master->call('helper/inline-css', $_params);
    158:     }
    159:
    160:     /**
    161:      * Retrieve minimal List data for all lists a member is subscribed to.
    162:      * @param associative_array $email
    163:      *     - email string an email address
    164:      *     - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
    165:      *     - 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
    166:      * @return array An array of structs with info on the  list_id the member is subscribed to.
    167:      *     - id string the list unique id
    168:      *     - the web_id id referenced in web interface urls
    169:      *     - the name list name
    170:      */
    171:     public function listsForEmail($email) {
    172:         $_params = array("email" => $email);
    173:         return $this->master->call('helper/lists-for-email', $_params);
    174:     }
    175:
    176:     /**
    177:      * "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good. Note
    178: than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different
    179: string back that will explain our view on what is going on.
    180:      * @return associative_array a with a "msg" key
    181:      *     - msg string containing "Everything's Chimpy!" if everything is chimpy, otherwise returns an error message
    182:      */
    183:     public function ping() {
    184:         $_params = array();
    185:         return $this->master->call('helper/ping', $_params);
    186:     }
    187:
    188:     /**
    189:      * Search all campaigns for the specified query terms
    190:      * @param string $query
    191:      * @param int $offset
    192:      * @param string $snip_start
    193:      * @param string $snip_end
    194:      * @return associative_array containing the total matches and current results
    195:      *     - total int total campaigns matching
    196:      *     - results array matching campaigns and snippets
    197:      *     - snippet string the matching snippet for the campaign
    198:      *     - campaign associative_array the matching campaign's details - will return same data as single campaign from campaigns/list()
    199:      *     - summary associative_array if available, the matching campaign's report/summary data, other wise empty
    200:      */
    201:     public function searchCampaigns($query, $offset=0, $snip_start=null, $snip_end=null) {
    202:         $_params = array("query" => $query, "offset" => $offset, "snip_start" => $snip_start, "snip_end" => $snip_end);
    203:         return $this->master->call('helper/search-campaigns', $_params);
    204:     }
    205:
    206:     /**
    207:      * Search account wide or on a specific list using the specified query terms
    208:      * @param string $query
    209:      * @param string $id
    210:      * @param int $offset
    211:      * @return associative_array An array of both exact matches and partial matches over a full search
    212:      *     - exact_matches associative_array containing the total matches and current results
    213:      *     - total int total members matching
    214:      *     - members array each entry will be struct matching the data format for a single member as returned by lists/member-info()
    215:      *     - full_search associative_array containing the total matches and current results
    216:      *     - total int total members matching
    217:      *     - members array each entry will be struct matching  the data format for a single member as returned by lists/member-info()
    218:      */
    219:     public function searchMembers($query, $id=null, $offset=0) {
    220:         $_params = array("query" => $query, "id" => $id, "offset" => $offset);
    221:         return $this->master->call('helper/search-members', $_params);
    222:     }
    223:
    224:     /**
    225:      * Retrieve all domain verification records for an account
    226:      * @return array structs for each domain verification has been attempted for
    227:      *     - domain string the verified domain
    228:      *     - status string the status of the verification - either "verified" or "pending"
    229:      *     - email string the email address used for verification - "pre-existing" if we automatically backfilled it at some point
    230:      */
    231:     public function verifiedDomains() {
    232:         $_params = array();
    233:         return $this->master->call('helper/verified-domains', $_params);
    234:     }
    235:
    236: }
    237:
    238:
    239: