1: <?php
2:
3: class Mailchimp_Reports {
4: public function __construct(Mailchimp $master) {
5: $this->master = $master;
6: }
7:
8: /**
9: * Get all email addresses that complained about a given campaign
10: * @param string $cid
11: * @param associative_array $opts
12: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
13: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
14: * - since string optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
15: * @return associative_array abuse report data for this campaign
16: * - total int the total reports matched
17: * - data array a struct for the each report, including:
18: * - date string date/time the abuse report was received and processed
19: * - member string the email address that reported abuse - will only contain email if the list or member has been removed
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 abuse($cid, $opts=array()) {
23: $_params = array("cid" => $cid, "opts" => $opts);
24: return $this->master->call('reports/abuse', $_params);
25: }
26:
27: /**
28: * Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
29: suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
30: * @param string $cid
31: * @return array of structs for advice on the campaign's performance, each containing:
32: * - msg string the advice message
33: * - type string the "type" of the message. one of: negative, positive, or neutral
34: */
35: public function advice($cid) {
36: $_params = array("cid" => $cid);
37: return $this->master->call('reports/advice', $_params);
38: }
39:
40: /**
41: * Retrieve the most recent full bounce message for a specific email address on the given campaign.
42: Messages over 30 days old are subject to being removed
43: * @param string $cid
44: * @param associative_array $email
45: * - email string an email address - this is recommended for this method
46: * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
47: * - 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
48: * @return associative_array the full bounce message for this email+campaign along with some extra data.
49: * - date string date the bounce was received and processed
50: * - member associative_array the member record as returned by lists/member-info()
51: * - message string the entire bounce message received
52: */
53: public function bounceMessage($cid, $email) {
54: $_params = array("cid" => $cid, "email" => $email);
55: return $this->master->call('reports/bounce-message', $_params);
56: }
57:
58: /**
59: * Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
60: of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
61: messages over 30 days old are subject to being removed
62: * @param string $cid
63: * @param associative_array $opts
64: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
65: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
66: * - since string optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
67: * @return associative_array data for the full bounce messages for this campaign
68: * - total int that total number of bounce messages for the campaign
69: * - data array structs containing the data for this page
70: * - date string date the bounce was received and processed
71: * - member associative_array the member record as returned by lists/member-info()
72: * - message string the entire bounce message received
73: */
74: public function bounceMessages($cid, $opts=array()) {
75: $_params = array("cid" => $cid, "opts" => $opts);
76: return $this->master->call('reports/bounce-messages', $_params);
77: }
78:
79: /**
80: * Return the list of email addresses that clicked on a given url, and how many times they clicked
81: * @param string $cid
82: * @param int $tid
83: * @param associative_array $opts
84: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
85: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
86: * - 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.
87: * - sort_dir string optional the direct - ASC or DESC. defaults to ASC (case insensitive)
88: * @return associative_array containing the total records matched and the specific records for this page
89: * - total int the total number of records matched
90: * - data array structs for each email addresses that click the requested url
91: * - member associative_array the member record as returned by lists/member-info()
92: * - clicks int Total number of times the URL was clicked by this email address
93: */
94: public function clickDetail($cid, $tid, $opts=array()) {
95: $_params = array("cid" => $cid, "tid" => $tid, "opts" => $opts);
96: return $this->master->call('reports/click-detail', $_params);
97: }
98:
99: /**
100: * The urls tracked and their click counts for a given campaign.
101: * @param string $cid
102: * @return associative_array including:
103: * - total array structs for each url tracked for the full campaign
104: * - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
105: * - clicks int Number of times the specific link was clicked
106: * - clicks_percent double the percentage of total clicks "clicks" represents
107: * - unique int Number of unique people who clicked on the specific link
108: * - unique_percent double the percentage of unique clicks "unique" represents
109: * - 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.
110: * - a array if this was an absplit campaign, stat structs for the a group
111: * - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
112: * - clicks int Number of times the specific link was clicked
113: * - clicks_percent double the percentage of total clicks "clicks" represents
114: * - unique int Number of unique people who clicked on the specific link
115: * - unique_percent double the percentage of unique clicks "unique" represents
116: * - 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.
117: * - b array if this was an absplit campaign, stat structs for the b group
118: * - url string the url being tracked - urls are tracked individually, so duplicates can exist with vastly different stats
119: * - clicks int Number of times the specific link was clicked
120: * - clicks_percent double the percentage of total clicks "clicks" represents
121: * - unique int Number of unique people who clicked on the specific link
122: * - unique_percent double the percentage of unique clicks "unique" represents
123: * - 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.
124: */
125: public function clicks($cid) {
126: $_params = array("cid" => $cid);
127: return $this->master->call('reports/clicks', $_params);
128: }
129:
130: /**
131: * Retrieve the Ecommerce Orders tracked by ecomm/order-add()
132: * @param string $cid
133: * @param associative_array $opts
134: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
135: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
136: * - since string optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg "2013-12-30 20:30:00"
137: * @return associative_array the total matching orders and the specific orders for the requested page
138: * - total int the total matching orders
139: * - data array structs for the actual data for each order being returned
140: * - store_id string the store id generated by the plugin used to uniquely identify a store
141: * - store_name string the store name collected by the plugin - often the domain name
142: * - order_id string the internal order id the store tracked this order by
143: * - member associative_array the member record as returned by lists/member-info() that received this campaign and is associated with this order
144: * - order_total double the order total
145: * - tax_total double the total tax for the order (if collected)
146: * - ship_total double the shipping total for the order (if collected)
147: * - order_date string the date the order was tracked - from the store if possible, otherwise the GMT time we received it
148: * - lines array structs containing details of the order:
149: * - line_num int the line number assigned to this line
150: * - product_id int the product id assigned to this item
151: * - product_name string the product name
152: * - product_sku string the sku for the product
153: * - product_category_id int the id for the product category
154: * - product_category_name string the product category name
155: * - qty double optional the quantity of the item ordered - defaults to 1
156: * - cost double optional the cost of a single item (ie, not the extended cost of the line) - defaults to 0
157: */
158: public function ecommOrders($cid, $opts=array()) {
159: $_params = array("cid" => $cid, "opts" => $opts);
160: return $this->master->call('reports/ecomm-orders', $_params);
161: }
162:
163: /**
164: * Retrieve the eepurl stats from the web/Twitter mentions for this campaign
165: * @param string $cid
166: * @return associative_array containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
167: * - twitter associative_array various Twitter related stats
168: * - tweets int Total number of tweets seen
169: * - first_tweet string date and time of the first tweet seen
170: * - last_tweet string date and time of the last tweet seen
171: * - retweets int Total number of retweets seen
172: * - first_retweet string date and time of the first retweet seen
173: * - last_retweet string date and time of the last retweet seen
174: * - statuses array an structs for statuses recorded including:
175: * - status string the text of the tweet/update
176: * - screen_name string the screen name as recorded when first seen
177: * - status_id string the status id of the tweet (they are really unsigned 64 bit ints)
178: * - datetime string the date/time of the tweet
179: * - is_retweet bool whether or not this was a retweet
180: * - clicks associative_array stats related to click-throughs on the eepurl
181: * - clicks int Total number of clicks seen
182: * - first_click string date and time of the first click seen
183: * - last_click string date and time of the first click seen
184: * - locations array structs for geographic locations including:
185: * - country string the country name the click was tracked to
186: * - region string the region in the country the click was tracked to (if available)
187: * - referrers array structs for referrers, including
188: * - referrer string the referrer, truncated to 100 bytes
189: * - clicks int Total number of clicks seen from this referrer
190: * - first_click string date and time of the first click seen from this referrer
191: * - last_click string date and time of the first click seen from this referrer
192: */
193: public function eepurl($cid) {
194: $_params = array("cid" => $cid);
195: return $this->master->call('reports/eepurl', $_params);
196: }
197:
198: /**
199: * 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
200: 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>,
201: <strong>not</strong> this, especially for large campaigns.
202: * @param string $cid
203: * @param array $emails
204: * - email string an email address
205: * - euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
206: * - 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
207: * @return associative_array of data and success/error counts
208: * - success_count int the number of subscribers successfully found on the list
209: * - error_count int the number of subscribers who were not found on the list
210: * - errors array array of error structs including:
211: * - email string whatever was passed in the email parameter
212: * - email string the email address added
213: * - euid string the email unique id
214: * - leid string the list member's truly unique id
215: * - msg string the error message
216: * - data array an array of structs where each activity record has:
217: * - email string whatever was passed in the email parameter
218: * - email string the email address added
219: * - euid string the email unique id
220: * - leid string the list member's truly unique id
221: * - member associative_array the member record as returned by lists/member-info()
222: * - activity array an array of structs containing the activity, including:
223: * - action string The action name - either open or click
224: * - timestamp string The date/time of the action (GMT)
225: * - url string For click actions, the url clicked, otherwise this is empty
226: * - ip string The IP address the activity came from
227: */
228: public function memberActivity($cid, $emails) {
229: $_params = array("cid" => $cid, "emails" => $emails);
230: return $this->master->call('reports/member-activity', $_params);
231: }
232:
233: /**
234: * Retrieve the list of email addresses that did not open a given campaign
235: * @param string $cid
236: * @param associative_array $opts
237: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
238: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
239: * @return associative_array a total of all matching emails and the specific emails for this page
240: * - total int the total number of members who didn't open the campaign
241: * - data array structs for each campaign member matching as returned by lists/member-info()
242: */
243: public function notOpened($cid, $opts=array()) {
244: $_params = array("cid" => $cid, "opts" => $opts);
245: return $this->master->call('reports/not-opened', $_params);
246: }
247:
248: /**
249: * Retrieve the list of email addresses that opened a given campaign with how many times they opened
250: * @param string $cid
251: * @param associative_array $opts
252: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
253: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
254: * - 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.
255: * - sort_dir string optional the direct - ASC or DESC. defaults to ASC (case insensitive)
256: * @return associative_array containing the total records matched and the specific records for this page
257: * - total int the total number of records matched
258: * - data array structs for the actual opens data, including:
259: * - member associative_array the member record as returned by lists/member-info()
260: * - opens int Total number of times the campaign was opened by this email address
261: */
262: public function opened($cid, $opts=array()) {
263: $_params = array("cid" => $cid, "opts" => $opts);
264: return $this->master->call('reports/opened', $_params);
265: }
266:
267: /**
268: * Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign reports/member-activity()
269: or campaignEmailStatsAIMAll() and generate any additional stats they require.
270: * @param string $cid
271: * @return array domains structs for each email domains and their associated stats
272: * - domain string Domain name or special "Other" to roll-up stats past 5 domains
273: * - total_sent int Total Email across all domains - this will be the same in every row
274: * - emails int Number of emails sent to this domain
275: * - bounces int Number of bounces
276: * - opens int Number of opens
277: * - clicks int Number of clicks
278: * - unsubs int Number of unsubs
279: * - delivered int Number of deliveries
280: * - emails_pct int Percentage of emails that went to this domain (whole number)
281: * - bounces_pct int Percentage of bounces from this domain (whole number)
282: * - opens_pct int Percentage of opens from this domain (whole number)
283: * - clicks_pct int Percentage of clicks from this domain (whole number)
284: * - unsubs_pct int Percentage of unsubs from this domain (whole number)
285: */
286: public function domainPerformance($cid) {
287: $_params = array("cid" => $cid);
288: return $this->master->call('reports/domain-performance', $_params);
289: }
290:
291: /**
292: * Retrieve the countries/regions and number of opens tracked for each. Email address are not returned.
293: * @param string $cid
294: * @return array an array of country structs where opens occurred
295: * - code string The ISO3166 2 digit country code
296: * - name string A version of the country name, if we have it
297: * - opens int The total number of opens that occurred in the country
298: * - regions array structs of data for each sub-region in the country
299: * - code string An internal code for the region. When this is blank, it indicates we know the country, but not the region
300: * - name string The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
301: * - opens int The total number of opens that occurred in the country
302: */
303: public function geoOpens($cid) {
304: $_params = array("cid" => $cid);
305: return $this->master->call('reports/geo-opens', $_params);
306: }
307:
308: /**
309: * Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
310: * @param string $cid
311: * @return array of structs for analytics we've collected for the passed campaign.
312: * - visits int number of visits
313: * - pages int number of page views
314: * - new_visits int new visits recorded
315: * - bounces int vistors who "bounced" from your site
316: * - time_on_site double the total time visitors spent on your sites
317: * - goal_conversions int number of goals converted
318: * - goal_value double value of conversion in dollars
319: * - revenue double revenue generated by campaign
320: * - transactions int number of transactions tracked
321: * - ecomm_conversions int number Ecommerce transactions tracked
322: * - goals array structs containing goal names and number of conversions
323: * - name string the name of the goal
324: * - conversions int the number of conversions for the goal
325: */
326: public function googleAnalytics($cid) {
327: $_params = array("cid" => $cid);
328: return $this->master->call('reports/google-analytics', $_params);
329: }
330:
331: /**
332: * Get email addresses the campaign was sent to
333: * @param string $cid
334: * @param associative_array $opts
335: * - status string optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
336: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
337: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
338: * @return associative_array a total of all matching emails and the specific emails for this page
339: * - total int the total number of members for the campaign and status
340: * - data array structs for each campaign member matching
341: * - member associative_array the member record as returned by lists/member-info()
342: * - status string the status of the send - one of 'sent', 'hard', 'soft'
343: * - absplit_group string if this was an absplit campaign, one of 'a','b', or 'winner'
344: * - tz_group string if this was an timewarp campaign the timezone GMT offset the member was included in
345: */
346: public function sentTo($cid, $opts=array()) {
347: $_params = array("cid" => $cid, "opts" => $opts);
348: return $this->master->call('reports/sent-to', $_params);
349: }
350:
351: /**
352: * 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)
353: * @param string $cid
354: * @param array $opts
355: * - 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
356: * - 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.
357: * - 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) <strong>only if</strong> loaded via the "secure_url" - max 255 bytes
358: * @return associative_array details for the shared report, including:
359: * - title string The Title of the Campaign being shared
360: * - url string The URL to the shared report
361: * - 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
362: * - password string If secured, the password for the report, otherwise this field will not be returned
363: */
364: public function share($cid, $opts=array()) {
365: $_params = array("cid" => $cid, "opts" => $opts);
366: return $this->master->call('reports/share', $_params);
367: }
368:
369: /**
370: * Retrieve relevant aggregate campaign statistics (opens, bounces, clicks, etc.)
371: * @param string $cid
372: * @return associative_array the statistics for this campaign
373: * - syntax_errors int Number of email addresses in campaign that had syntactical errors.
374: * - hard_bounces int Number of email addresses in campaign that hard bounced.
375: * - soft_bounces int Number of email addresses in campaign that soft bounced.
376: * - unsubscribes int Number of email addresses in campaign that unsubscribed.
377: * - abuse_reports int Number of email addresses in campaign that reported campaign for abuse.
378: * - forwards int Number of times email was forwarded to a friend.
379: * - forwards_opens int Number of times a forwarded email was opened.
380: * - opens int Number of times the campaign was opened.
381: * - last_open string Date of the last time the email was opened.
382: * - unique_opens int Number of people who opened the campaign.
383: * - clicks int Number of times a link in the campaign was clicked.
384: * - unique_clicks int Number of unique recipient/click pairs for the campaign.
385: * - last_click string Date of the last time a link in the email was clicked.
386: * - users_who_clicked int Number of unique recipients who clicked on a link in the campaign.
387: * - emails_sent int Number of email addresses campaign was sent to.
388: * - unique_likes int total number of unique likes (Facebook)
389: * - recipient_likes int total number of recipients who liked (Facebook) the campaign
390: * - facebook_likes int total number of likes (Facebook) that came from Facebook
391: * - 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.
392: * - type string the selected industry
393: * - open_rate float industry open rate
394: * - click_rate float industry click rate
395: * - bounce_rate float industry bounce rate
396: * - unopen_rate float industry unopen rate
397: * - unsub_rate float industry unsub rate
398: * - abuse_rate float industry abuse rate
399: * - absplit associative_array If this was an absplit campaign, stats for the A and B groups will be returned - otherwise this is empty
400: * - bounces_a int bounces for the A group
401: * - bounces_b int bounces for the B group
402: * - forwards_a int forwards for the A group
403: * - forwards_b int forwards for the B group
404: * - abuse_reports_a int abuse reports for the A group
405: * - abuse_reports_b int abuse reports for the B group
406: * - unsubs_a int unsubs for the A group
407: * - unsubs_b int unsubs for the B group
408: * - recipients_click_a int clicks for the A group
409: * - recipients_click_b int clicks for the B group
410: * - forwards_opens_a int opened forwards for the A group
411: * - forwards_opens_b int opened forwards for the B group
412: * - opens_a int total opens for the A group
413: * - opens_b int total opens for the B group
414: * - last_open_a string date/time of last open for the A group
415: * - last_open_b string date/time of last open for the BG group
416: * - unique_opens_a int unique opens for the A group
417: * - unique_opens_b int unique opens for the B group
418: * - timewarp array If this campaign was a Timewarp campaign, an array of structs from each timezone stats exist for. Each will contain:
419: * - opens int opens for this timezone
420: * - last_open string the date/time of the last open for this timezone
421: * - unique_opens int the unique opens for this timezone
422: * - clicks int the total clicks for this timezone
423: * - last_click string the date/time of the last click for this timezone
424: * - unique_opens int the unique clicks for this timezone
425: * - bounces int the total bounces for this timezone
426: * - total int the total number of members sent to in this timezone
427: * - sent int the total number of members delivered to in this timezone
428: * - timeseries array structs for the first 24 hours of the campaign, per-hour stats:
429: * - timestamp string The timestemp in Y-m-d H:00:00 format
430: * - emails_sent int the total emails sent during the hour
431: * - unique_opens int unique opens seen during the hour
432: * - recipients_click int unique clicks seen during the hour
433: */
434: public function summary($cid) {
435: $_params = array("cid" => $cid);
436: return $this->master->call('reports/summary', $_params);
437: }
438:
439: /**
440: * Get all unsubscribed email addresses for a given campaign
441: * @param string $cid
442: * @param associative_array $opts
443: * - start int optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
444: * - limit int optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100
445: * @return associative_array a total of all unsubscribed emails and the specific members for this page
446: * - total int the total number of unsubscribes for the campaign
447: * - data array structs for the email addresses that unsubscribed
448: * - member string the member that unsubscribed as returned by lists/member-info()
449: * - reason string the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
450: * - reason_text string if the reason is OTHER, the text entered.
451: */
452: public function unsubscribes($cid, $opts=array()) {
453: $_params = array("cid" => $cid, "opts" => $opts);
454: return $this->master->call('reports/unsubscribes', $_params);
455: }
456:
457: }
458:
459:
460: