The purpose of this call is to allow the user to return various resources ("dataset") associated with one or more campaigns depending on the optional parameter values used in a specific call.  


JSON Request Example:     

{
  "username": "JohnDoe",
  "usertoken": "abc123abc123abc123abc123",
  "requesttype": "Newsletters",
  "requestmethod": "GetNewsletterResults",
  "details": {
    "newsletterid": "{*newsletter_id*}",
    "newslettername": "{*newsletter_name*}",
    "grouping": "{*string: newsletter|batch|send*}",
    "intervalcount": "{*interval_count_integer*}",
    "intervalunits": "{*interval_units*}",
    "startdate": "{*start_date*}",
    "enddate": "{*end_date*}",
    "pagination": "{
    	"limit": "{*max_records*}",
        "next": "{*start_at_record_number*}"
    }    
  }
}
Null


"json_request"  element


Field NameDescription
usernameUsername used to login to Pinpointe
usertokenUnique token assigned to Pinpointe account
requesttypeNewsletters
requestmethodGetNewsletterResults


"details" element


Please note: Unused optional parameters should be deleted from the call. 


Please note: Do NOT use “intervalcount” and “intervalunits” fields AND “startdate” and “enddate” fields

simultaneously in same API call. Doing so can cause conflicts.


Field Name
Description
newsletterid
(optional)		Newsletter ID.
NOTE: If omitted, datasets for ALL campaigns will be returned (what exactly will be returned is predicated on other field options used – more on that below)
newslettername
(Optional and alternate)		Newsletter name. 
NOTE: User should specify either a newsletter ID or name, but both parameters should NOT be used.  
grouping
(optional)		There are three optional values for this field:

▪ “newsletter” -> (also the default should the field be omitted altogether). All sends (each

send being identified by a stat_id within Pinpointe) will be aggregated together into one

dataset for a given newsletter_id. So, if newsletter_id 25025 had been sent 11 times for

the time period being queried, the send metrics for all 11 stat_ids would be aggregated.


▪ “batch” -> This will return each send (stat_id) for a given newsletter_id. In the example

above, 11 separate datasets would be returned.


▪ “send” -> This will return a dataset for every child batch send for a given parent send

stat_id. For example, if newsletter_id had been sent twice, there would be two parent

sends, (ex: stat_id 44000 and 45000), and if each of these two sends had been sent in

three batches (ex: 44001, 44002, 44003 and 45001, 45002, 45003), this call would return

six separate datasets, each being the dataset for the respective batch send. The

aggregated stat dataset for 44000 and 44001 would NOT be returned.

If the user wishes to get the aggregated dataset for the parent send, they should set

“grouping” to “batch”, OR, user could aggregate the individual batch sends themselves

locally programmatically.


In addition, if using “send”, a dataset for each non-batched send is also returned, though

in this case there is only one ‘batch’ for that parent send.

So, following the example above, if the user had three sends for the newsletter_id (send

stat_id 44000 and 45000, sent in three separate batches each) AND had sent a non-batch

send (stat_id 46000), selecting “send” would return seven datasets: the six individual

batches for 44000 and 45000, and the dataset for 46000. A non-batched send will be

treated as its own batch send using “send”.


intervalcount
(optional)		The interval count used in conjunction with "intervalunits". Must be an integer.
For example, if the intervalcount value is "7", and the interval unit is "month", then the call would return results for past seven months.
NOTE: If “intervalcount” given but NO “intervalunits”, time unit is assumed a “day”.
intervalunits
(optional)
The interval time unit, which can be any of these four units of time measurement:
1. "day"
2. "week"
3. "month"
4. "year"
NOTE: If “intervalunits” given but NO “intervalcount”, count is assumed “1”.
startdate
(optional)		Start date must be in the "YYYYMMDD" format.

NOTE: If both "startdate" and "enddate" omitted, all sends since inception of account are included in returned datasets.

NOTE: If “startdate” given but NO “enddate”, ALL newsletters sent AFTER “startdate” are included.
enddate
(optional)		End date must be in the "YYYYMMDD" format.

NOTE: If both "startdate" and "enddate" omitted, all sends since inception of account are included in returned datasets.

NOTE: If “enddate” given but NO “startdate”, ALL newsletters sent BEFORE “enddate” are included.


"pagination" element


Please note: If "pagination" parameters omitted, call will return as many records as allowable based on current application memory constraints.  


Field Name
Description
limit
(optional but required if "next" parameter used)		max_records: Integer indicating maximum number of datasets (records) to be returned for the respective call.
next
(optional)		start_at_record_number: If parameter used, the call response will be limited to the “limit” value and the response will include a pagination section with the appropriate “next” value to return the next sequential chunk of records, or “0” if all records have been returned.


Successful Response:


"response" element


Field NameDescription
statusWill return SUCCESS if newsletter stat id is successfully retrieved


"response" "data" and "item" elements


Field NameDescription
count
Total number of "stats" datasets returned 
grouping"grouping " parameter value used in call
stats A dataset of relevant data per newsletter send returned


Unsuccessful Response:


"response" element


Field NameDescription
statusWill return FAILED if unsuccessful
errormessageText explaining why request failed