22

✏️ Editing: Reports.php

<?php

class Mailchimp_Reports {
    public function __construct(Mailchimp $master) {
        $this->master = $master;
    }

/**
 * Get all email addresses that complained about a given campaign
 * @param string $cid
 * @param associative_array $opts
 * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
 * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
 * - since string optional pull only messages since this time - 24 hour format in GMT, eg "2013-12-30 20:30:00"
 * @return associative_array abuse report data for this campaign
 * - total int the total reports matched
 * - data array a struct for the each report, including:
 * - date string date/time the abuse report was received and processed
 * - member string the email address that reported abuse - will only contain email if the list or member has been removed
 * - type string an internal type generally specifying the originating mail provider - may not be useful outside of filling report views
 */
 public function abuse($cid, $opts=array()) {
 $_params = array("cid" => $cid, "opts" => $opts);
 return $this->master->call('reports/abuse', $_params);
 }

/**
     * Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
     * @param string $cid
     * @return array of structs for advice on the campaign's performance, each containing:
     *     - msg string the advice message
     *     - type string the "type" of the message. one of: negative, positive, or neutral
     */
    public function advice($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/advice', $_params);
    }

/**
     * Retrieve the most recent full bounce message for a specific email address on the given campaign.
Messages over 30 days old are subject to being removed
     * @param string $cid
     * @param associative_array $email
     *     - email string an email address - this is recommended for this method
     *     - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
     *     - 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
     * @return associative_array the full bounce message for this email+campaign along with some extra data.
     *     - date string date the bounce was received and processed
     *     - member associative_array the member record as returned by lists/member-info()
     *     - message string the entire bounce message received
     */
    public function bounceMessage($cid, $email) {
        $_params = array("cid" => $cid, "email" => $email);
        return $this->master->call('reports/bounce-message', $_params);
    }

/**
 * Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
messages over 30 days old are subject to being removed
 * @param string $cid
 * @param associative_array $opts
 * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
 * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
 * - since string optional pull only messages since this time - 24 hour format in GMT, eg "2013-12-30 20:30:00"
 * @return associative_array data for the full bounce messages for this campaign
 * - total int that total number of bounce messages for the campaign
 * - data array structs containing the data for this page
 * - date string date the bounce was received and processed
 * - member associative_array the member record as returned by lists/member-info()
 * - message string the entire bounce message received
 */
 public function bounceMessages($cid, $opts=array()) {
 $_params = array("cid" => $cid, "opts" => $opts);
 return $this->master->call('reports/bounce-messages', $_params);
 }

/**
     * Return the list of email addresses that clicked on a given url, and how many times they clicked
     * @param string $cid
     * @param int $tid
     * @param associative_array $opts
     *     - start int optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
     *     - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
     *     - sort_field string optional the data to sort by - "clicked" (order clicks occurred, default) or "clicks" (total number of opens). Invalid fields will fall back on the default.
     *     - sort_dir string optional the direct - ASC or DESC. defaults to ASC (case insensitive)
     * @return associative_array containing the total records matched and the specific records for this page
     *     - total int the total number of records matched
     *     - data array structs for each email addresses that click the requested url
     *         - member associative_array the member record as returned by lists/member-info()
     *         - clicks int Total number of times the URL was clicked by this email address
     */
    public function clickDetail($cid, $tid, $opts=array()) {
        $_params = array("cid" => $cid, "tid" => $tid, "opts" => $opts);
        return $this->master->call('reports/click-detail', $_params);
    }

/**
     * The urls tracked and their click counts for a given campaign.
     * @param string $cid
     * @return associative_array including:
     *     - total array structs for each url tracked for the full campaign
     *         - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
     *         - clicks int Number of times the specific link was clicked
     *         - clicks_percent double the percentage of total clicks "clicks" represents
     *         - unique int Number of unique people who clicked on the specific link
     *         - unique_percent double the percentage of unique clicks "unique" represents
     *         - tid int the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
     *     - a array if this was an absplit campaign, stat structs for the a group
     *         - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
     *         - clicks int Number of times the specific link was clicked
     *         - clicks_percent double the percentage of total clicks "clicks" represents
     *         - unique int Number of unique people who clicked on the specific link
     *         - unique_percent double the percentage of unique clicks "unique" represents
     *         - tid int the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
     *     - b array if this was an absplit campaign, stat structs for the b group
     *         - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
     *         - clicks int Number of times the specific link was clicked
     *         - clicks_percent double the percentage of total clicks "clicks" represents
     *         - unique int Number of unique people who clicked on the specific link
     *         - unique_percent double the percentage of unique clicks "unique" represents
     *         - tid int the tracking id used in campaign links - used primarily for reports/click-activity. also can be used to order urls by the order they appeared in the campaign to recreate our heat map.
     */
    public function clicks($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/clicks', $_params);
    }

/**
 * Retrieve the Ecommerce Orders tracked by ecomm/order-add()
 * @param string $cid
 * @param associative_array $opts
 * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
 * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
 * - since string optional pull only messages since this time - 24 hour format in GMT, eg "2013-12-30 20:30:00"
 * @return associative_array the total matching orders and the specific orders for the requested page
 * - total int the total matching orders
 * - data array structs for the actual data for each order being returned
 * - store_id string the store id generated by the plugin used to uniquely identify a store
 * - store_name string the store name collected by the plugin - often the domain name
 * - order_id string the internal order id the store tracked this order by
 * - member associative_array the member record as returned by lists/member-info() that received this campaign and is associated with this order
 * - order_total double the order total
 * - tax_total double the total tax for the order (if collected)
 * - ship_total double the shipping total for the order (if collected)
 * - order_date string the date the order was tracked - from the store if possible, otherwise the GMT time we received it
 * - lines array structs containing details of the order:
 * - line_num int the line number assigned to this line
 * - product_id int the product id assigned to this item
 * - product_name string the product name
 * - product_sku string the sku for the product
 * - product_category_id int the id for the product category
 * - product_category_name string the product category name
 * - qty double optional the quantity of the item ordered - defaults to 1
 * - cost double optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
 */
 public function ecommOrders($cid, $opts=array()) {
 $_params = array("cid" => $cid, "opts" => $opts);
 return $this->master->call('reports/ecomm-orders', $_params);
 }

/**
     * Retrieve the eepurl stats from the web/Twitter mentions for this campaign
     * @param string $cid
     * @return associative_array containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
     *     - twitter associative_array various Twitter related stats
     *         - tweets int Total number of tweets seen
     *         - first_tweet string date and time of the first tweet seen
     *         - last_tweet string date and time of the last tweet seen
     *         - retweets int Total number of retweets seen
     *         - first_retweet string date and time of the first retweet seen
     *         - last_retweet string date and time of the last retweet seen
     *         - statuses array an structs for statuses recorded including:
     *             - status string the text of the tweet/update
     *             - screen_name string the screen name as recorded when first seen
     *             - status_id string the status id of the tweet (they are really unsigned 64 bit ints)
     *             - datetime string the date/time of the tweet
     *             - is_retweet bool whether or not this was a retweet
     *     - clicks associative_array stats related to click-throughs on the eepurl
     *         - clicks int Total number of clicks seen
     *         - first_click string date and time of the first click seen
     *         - last_click string date and time of the first click seen
     *         - locations array structs for geographic locations including:
     *             - country string the country name the click was tracked to
     *             - region string the region in the country the click was tracked to (if available)
     *     - referrers array structs for referrers, including
     *         - referrer string the referrer, truncated to 100 bytes
     *         - clicks int Total number of clicks seen from this referrer
     *         - first_click string date and time of the first click seen from this referrer
     *         - last_click string date and time of the first click seen from this referrer
     */
    public function eepurl($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/eepurl', $_params);
    }

/**
 * Given a campaign and email address, return the entire click and open history with timestamps, ordered by time. If you need to dump the full activity for a campaign
and/or get incremental results, you should use the <a href="http://apidocs.mailchimp.com/export/1.0/campaignsubscriberactivity.func.php" targret="_new">campaignSubscriberActivity Export API method</a>,
not this, especially for large campaigns.
 * @param string $cid
 * @param array $emails
 * - email string an email address
 * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
 * - 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
 * @return associative_array of data and success/error counts
 * - success_count int the number of subscribers successfully found on the list
 * - error_count int the number of subscribers who were not found on the list
 * - errors array array of error structs including:
 * - email string whatever was passed in the email parameter
 * - email string the email address added
 * - euid string the email unique id
 * - leid string the list member's truly unique id
 * - msg string the error message
 * - data array an array of structs where each activity record has:
 * - email string whatever was passed in the email parameter
 * - email string the email address added
 * - euid string the email unique id
 * - leid string the list member's truly unique id
 * - member associative_array the member record as returned by lists/member-info()
 * - activity array an array of structs containing the activity, including:
 * - action string The action name - either open or click
 * - timestamp string The date/time of the action (GMT)
 * - url string For click actions, the url clicked, otherwise this is empty
 * - ip string The IP address the activity came from
 */
 public function memberActivity($cid, $emails) {
 $_params = array("cid" => $cid, "emails" => $emails);
 return $this->master->call('reports/member-activity', $_params);
 }

/**
     * Retrieve the list of email addresses that did not open a given campaign
     * @param string $cid
     * @param associative_array $opts
     *     - start int optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
     *     - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
     * @return associative_array a total of all matching emails and the specific emails for this page
     *     - total int the total number of members who didn't open the campaign
     *     - data array structs for each campaign member matching as returned by lists/member-info()
     */
    public function notOpened($cid, $opts=array()) {
        $_params = array("cid" => $cid, "opts" => $opts);
        return $this->master->call('reports/not-opened', $_params);
    }

/**
     * Retrieve the list of email addresses that opened a given campaign with how many times they opened
     * @param string $cid
     * @param associative_array $opts
     *     - start int optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
     *     - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
     *     - sort_field string optional the data to sort by - "opened" (order opens occurred, default) or "opens" (total number of opens). Invalid fields will fall back on the default.
     *     - sort_dir string optional the direct - ASC or DESC. defaults to ASC (case insensitive)
     * @return associative_array containing the total records matched and the specific records for this page
     *     - total int the total number of records matched
     *     - data array structs for the actual opens data, including:
     *         - member associative_array the member record as returned by lists/member-info()
     *         - opens int Total number of times the campaign was opened by this email address
     */
    public function opened($cid, $opts=array()) {
        $_params = array("cid" => $cid, "opts" => $opts);
        return $this->master->call('reports/opened', $_params);
    }

/**
     * Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign reports/member-activity()
or campaignEmailStatsAIMAll() and generate any additional stats they require.
     * @param string $cid
     * @return array domains structs for each email domains and their associated stats
     *     - domain string Domain name or special "Other" to roll-up stats past 5 domains
     *     - total_sent int Total Email across all domains - this will be the same in every row
     *     - emails int Number of emails sent to this domain
     *     - bounces int Number of bounces
     *     - opens int Number of opens
     *     - clicks int Number of clicks
     *     - unsubs int Number of unsubs
     *     - delivered int Number of deliveries
     *     - emails_pct int Percentage of emails that went to this domain (whole number)
     *     - bounces_pct int Percentage of bounces from this domain (whole number)
     *     - opens_pct int Percentage of opens from this domain (whole number)
     *     - clicks_pct int Percentage of clicks from this domain (whole number)
     *     - unsubs_pct int Percentage of unsubs from this domain (whole number)
     */
    public function domainPerformance($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/domain-performance', $_params);
    }

/**
     * Retrieve the countries/regions and number of opens tracked for each. Email address are not returned.
     * @param string $cid
     * @return array an array of country structs where opens occurred
     *     - code string The ISO3166 2 digit country code
     *     - name string A version of the country name, if we have it
     *     - opens int The total number of opens that occurred in the country
     *     - regions array structs of data for each sub-region in the country
     *         - code string An internal code for the region. When this is blank, it indicates we know the country, but not the region
     *         - name string The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
     *         - opens int The total number of opens that occurred in the country
     */
    public function geoOpens($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/geo-opens', $_params);
    }

/**
     * Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
     * @param string $cid
     * @return array of structs for analytics we've collected for the passed campaign.
     *     - visits int number of visits
     *     - pages int number of page views
     *     - new_visits int new visits recorded
     *     - bounces int vistors who "bounced" from your site
     *     - time_on_site double the total time visitors spent on your sites
     *     - goal_conversions int number of goals converted
     *     - goal_value double value of conversion in dollars
     *     - revenue double revenue generated by campaign
     *     - transactions int number of transactions tracked
     *     - ecomm_conversions int number Ecommerce transactions tracked
     *     - goals array structs containing goal names and number of conversions
     *         - name string the name of the goal
     *         - conversions int the number of conversions for the goal
     */
    public function googleAnalytics($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/google-analytics', $_params);
    }

/**
     * Get email addresses the campaign was sent to
     * @param string $cid
     * @param associative_array $opts
     *     - status string optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
     *     - start int optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
     *     - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
     * @return associative_array a total of all matching emails and the specific emails for this page
     *     - total int the total number of members for the campaign and status
     *     - data array structs for each campaign member matching
     *         - member associative_array the member record as returned by lists/member-info()
     *         - status string the status of the send - one of 'sent', 'hard', 'soft'
     *         - absplit_group string if this was an absplit campaign, one of 'a','b', or 'winner'
     *         - tz_group string if this was an timewarp campaign the timezone GMT offset the member was included in
     */
    public function sentTo($cid, $opts=array()) {
        $_params = array("cid" => $cid, "opts" => $opts);
        return $this->master->call('reports/sent-to', $_params);
    }

/**
 * Get the URL to a customized <a href="http://eepurl.com/gKmL" target="_blank">VIP Report</a> for the specified campaign and optionally send an email to someone with links to it. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)
 * @param string $cid
 * @param array $opts
 * - to_email string optional - optional, comma delimited list of email addresses to share the report with - no value means an email will not be sent
 * - theme_id int optional - either a global or a user-specific theme id. Currently this needs to be pulled out of either the Share Report or Cobranding web views by grabbing the "theme" attribute from the list presented.
 * - css_url string optional - a link to an external CSS file to be included after our default CSS (http://vip-reports.net/css/vip.css) only if loaded via the "secure_url" - max 255 bytes
 * @return associative_array details for the shared report, including:
 * - title string The Title of the Campaign being shared
 * - url string The URL to the shared report
 * - secure_url string The URL to the shared report, including the password (good for loading in an IFRAME). For non-secure reports, this will not be returned
 * - password string If secured, the password for the report, otherwise this field will not be returned
 */
 public function share($cid, $opts=array()) {
 $_params = array("cid" => $cid, "opts" => $opts);
 return $this->master->call('reports/share', $_params);
 }

/**
     * Retrieve relevant aggregate campaign statistics (opens, bounces, clicks, etc.)
     * @param string $cid
     * @return associative_array the statistics for this campaign
     *     - syntax_errors int Number of email addresses in campaign that had syntactical errors.
     *     - hard_bounces int Number of email addresses in campaign that hard bounced.
     *     - soft_bounces int Number of email addresses in campaign that soft bounced.
     *     - unsubscribes int Number of email addresses in campaign that unsubscribed.
     *     - abuse_reports int Number of email addresses in campaign that reported campaign for abuse.
     *     - forwards int Number of times email was forwarded to a friend.
     *     - forwards_opens int Number of times a forwarded email was opened.
     *     - opens int Number of times the campaign was opened.
     *     - last_open string Date of the last time the email was opened.
     *     - unique_opens int Number of people who opened the campaign.
     *     - clicks int Number of times a link in the campaign was clicked.
     *     - unique_clicks int Number of unique recipient/click pairs for the campaign.
     *     - last_click string Date of the last time a link in the email was clicked.
     *     - users_who_clicked int Number of unique recipients who clicked on a link in the campaign.
     *     - emails_sent int Number of email addresses campaign was sent to.
     *     - unique_likes int total number of unique likes (Facebook)
     *     - recipient_likes int total number of recipients who liked (Facebook) the campaign
     *     - facebook_likes int total number of likes (Facebook) that came from Facebook
     *     - industry associative_array Various rates/percentages for the account's selected industry - empty otherwise. These will vary across calls, do not use them for anything important.
     *         - type string the selected industry
     *         - open_rate float industry open rate
     *         - click_rate float industry click rate
     *         - bounce_rate float industry bounce rate
     *         - unopen_rate float industry unopen rate
     *         - unsub_rate float industry unsub rate
     *         - abuse_rate float industry abuse rate
     *     - absplit associative_array If this was an absplit campaign, stats for the A and B groups will be returned - otherwise this is empty
     *         - bounces_a int bounces for the A group
     *         - bounces_b int bounces for the B group
     *         - forwards_a int forwards for the A group
     *         - forwards_b int forwards for the B group
     *         - abuse_reports_a int abuse reports for the A group
     *         - abuse_reports_b int abuse reports for the B group
     *         - unsubs_a int unsubs for the A group
     *         - unsubs_b int unsubs for the B group
     *         - recipients_click_a int clicks for the A group
     *         - recipients_click_b int clicks for the B group
     *         - forwards_opens_a int opened forwards for the A group
     *         - forwards_opens_b int opened forwards for the B group
     *         - opens_a int total opens for the A group
     *         - opens_b int total opens for the B group
     *         - last_open_a string date/time of last open for the A group
     *         - last_open_b string date/time of last open for the BG group
     *         - unique_opens_a int unique opens for the A group
     *         - unique_opens_b int unique opens for the B group
     *     - timewarp array If this campaign was a Timewarp campaign, an array of structs from each timezone stats exist for. Each will contain:
     *         - opens int opens for this timezone
     *         - last_open string the date/time of the last open for this timezone
     *         - unique_opens int the unique opens for this timezone
     *         - clicks int the total clicks for this timezone
     *         - last_click string the date/time of the last click for this timezone
     *         - unique_opens int the unique clicks for this timezone
     *         - bounces int the total bounces for this timezone
     *         - total int the total number of members sent to in this timezone
     *         - sent int the total number of members delivered to in this timezone
     *     - timeseries array structs for the first 24 hours of the campaign, per-hour stats:
     *         - timestamp string The timestemp in Y-m-d H:00:00 format
     *         - emails_sent int the total emails sent during the hour
     *         - unique_opens int unique opens seen during the hour
     *         - recipients_click int unique clicks seen during the hour
     */
    public function summary($cid) {
        $_params = array("cid" => $cid);
        return $this->master->call('reports/summary', $_params);
    }

/**
     * Get all unsubscribed email addresses for a given campaign
     * @param string $cid
     * @param associative_array $opts
     *     - start int optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
     *     - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
     * @return associative_array a total of all unsubscribed emails and the specific members for this page
     *     - total int the total number of unsubscribes for the campaign
     *     - data array structs for the email addresses that unsubscribed
     *         - member string the member that unsubscribed as returned by lists/member-info()
     *         - reason string the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
     *         - reason_text string if the reason is OTHER, the text entered.
     */
    public function unsubscribes($cid, $opts=array()) {
        $_params = array("cid" => $cid, "opts" => $opts);
        return $this->master->call('reports/unsubscribes', $_params);
    }

}

MR SKB