Methods summary
public
|
|
public
associative_array
|
#
abuse( string $cid, associative_array $opts = array() )
Get all email addresses that complained about a given campaign
Get all email addresses that complained about a given campaign
Parameters
- $cid
string $cid
- $opts
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
<strong>GMT</strong>, eg "2013-12-30 20:30:00"
Returns
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
array
|
#
advice( string $cid )
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
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
Parameters
Returns
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
associative_array
|
#
bounceMessage( string $cid, associative_array $email )
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
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
Parameters
- $cid
string $cid
- $email
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
Returns
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
associative_array
|
#
bounceMessages( string $cid, associative_array $opts = array() )
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
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
Parameters
- $cid
string $cid
- $opts
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
<strong>GMT</strong>, eg "2013-12-30 20:30:00"
Returns
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
associative_array
|
#
clickDetail( string $cid, integer $tid, associative_array $opts = array() )
Return the list of email addresses that clicked on a given url, and how many
times they clicked
Return the list of email addresses that clicked on a given url, and how many
times they clicked
Parameters
- $cid
string $cid
- $tid
integer $tid
- $opts
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)
Returns
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
associative_array
|
#
clicks( string $cid )
The urls tracked and their click counts for a given campaign.
The urls tracked and their click counts for a given campaign.
Parameters
Returns
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
associative_array
|
#
ecommOrders( string $cid, associative_array $opts = array() )
Retrieve the Ecommerce Orders tracked by ecomm/order-add()
Retrieve the Ecommerce Orders tracked by ecomm/order-add()
Parameters
- $cid
string $cid
- $opts
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
<strong>GMT</strong>, eg "2013-12-30 20:30:00"
Returns
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
associative_array
|
#
eepurl( string $cid )
Retrieve the eepurl stats from the web/Twitter mentions for this campaign
Retrieve the eepurl stats from the web/Twitter mentions for this campaign
Parameters
Returns
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
associative_array
|
#
memberActivity( string $cid, array $emails )
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 campaignSubscriberActivity
Export API method, <strong>not</strong> this, especially for
large campaigns.
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 campaignSubscriberActivity
Export API method, <strong>not</strong> this, especially for
large campaigns.
Parameters
- $cid
string $cid
- $emails
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
Returns
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
associative_array
|
#
notOpened( string $cid, associative_array $opts = array() )
Retrieve the list of email addresses that did not open a given campaign
Retrieve the list of email addresses that did not open a given campaign
Parameters
- $cid
string $cid
- $opts
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
Returns
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
associative_array
|
#
opened( string $cid, associative_array $opts = array() )
Retrieve the list of email addresses that opened a given campaign with how
many times they opened
Retrieve the list of email addresses that opened a given campaign with how
many times they opened
Parameters
- $cid
string $cid
- $opts
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)
Returns
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
array
|
#
domainPerformance( string $cid )
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.
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.
Parameters
Returns
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
array
|
#
geoOpens( string $cid )
Retrieve the countries/regions and number of opens tracked for each. Email
address are not returned.
Retrieve the countries/regions and number of opens tracked for each. Email
address are not returned.
Parameters
Returns
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
array
|
#
googleAnalytics( string $cid )
Retrieve the Google Analytics data we've collected for this campaign. Note,
requires Google Analytics Add-on to be installed and configured.
Retrieve the Google Analytics data we've collected for this campaign. Note,
requires Google Analytics Add-on to be installed and configured.
Parameters
Returns
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
associative_array
|
#
sentTo( string $cid, associative_array $opts = array() )
Get email addresses the campaign was sent to
Get email addresses the campaign was sent to
Parameters
- $cid
string $cid
- $opts
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
Returns
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
associative_array
|
#
share( string $cid, array $opts = array() )
Get the URL to a customized VIP Report 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)
Get the URL to a customized VIP Report 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)
Parameters
- $cid
string $cid
- $opts
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)
<strong>only if</strong> loaded via the "secure_url" - max 255 bytes
Returns
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
associative_array
|
#
summary( string $cid )
Retrieve relevant aggregate campaign statistics (opens, bounces, clicks,
etc.)
Retrieve relevant aggregate campaign statistics (opens, bounces, clicks,
etc.)
Parameters
Returns
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
associative_array
|
#
unsubscribes( string $cid, associative_array $opts = array() )
Get all unsubscribed email addresses for a given campaign
Get all unsubscribed email addresses for a given campaign
Parameters
- $cid
string $cid
- $opts
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
Returns
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.
|