API: HTTP Report Tracked Events

The Report Tracked Events group of commands allow you to return a list of contacts for a specified tracked event type in a date range, by normal campaign type, related to API sends only, or both. The commands include:

Event Type	Sent as Campaign	Sent as One-Off Message via API	Both
Sent	rpt_send_events	rpt_api_send_events	rpt_all_send_events
Open	rpt_open_events	rpt_api_open_events	rpt_all_open_events
Click	rpt_click_events	rpt_api_click_events	rpt_all_click_events
Delivery Hard Bounce Soft Bounce Blocked Bounce Complaint	rpt_delivery_events	rpt_api_delivery_events	rpt_all_delivery_events
Unsubscribe			rpt_unsub_events
Video			rpt_video_events
Social			rpt_social_events
All Other Events			rpt_tracking_other_events

The commands require the following arguments: Command, Realm, Password, Start (From) Date, and End (To) Date.

api_web?r=myrealm&p=mypass&c=rpt_open_events&offset=0&start_datetime=06/20/2017%2000:00:00&end_datetime=06/20/2017%2011:59:59

The command is ‘rpt_open_events’, the realm is ‘myrealm’ and the password is ‘mypass’. The command will return every Open event from deployed campaigns that occurred from 12:00 am on June 20, 2017 to just before midnight on the same day starting with the first result (offset=0). The report will include the first 250 events with the event details including, but not limited to:

"campaign_id","campaign_alias","list_id","list_name","subscriber_id","email","first_name","last_name","event_date"

Because tracked events do not all store the same types of information, the data returned will vary.

Example

Using all commands and arguments for an ALL version of the command (please note the command is wrapped for display purposes only):

api_web?c=rpt_all_send_events&r=myrealm&p=mypass&start_datetime=06/20/2017%2000:00:00&end_datetime=06/20/2017%2011:59:59&output_format=csv&headers=1

Successful results return:

"campaign_id","campaign_alias","list_id","list_name","subscriber_id","email","first_name","last_name","event_date","event_type","tracking_id"

"10","Alias","42","my list","13","jack@myemail.com","Jack","Sprat","2017-06-20 10:00:09","9","4456"
"10","Alias","42","my list","14","jane@myemail.com","Jane","Doe","2017-06-20 10:00:09","9","4457"
"11","Alias API 1","42","my list","13","jack@myemail.com","Jack","Sprat","2017-06-20 10:48:25","70","4566"
"12","Alias API 2","42","my list","14","jane@myemail.com","Jane","Doe","2017-06-20 11:48:25","70","4567"

Using all commands and arguments for a simple version of the command (please note the command is wrapped for display purposes only):

api_web?c=rpt_send_events&r=myrealm&p=mypass&offset=0&start_datetime=06/20/2017%2000:00:00&end_datetime=06/20/2017%2011:59:59&output_format=csv&headers=1

Successful results return:

"campaign_id","campaign_alias","list_id","list_name","subscriber_id","email","first_name","last_name","event_date","event_type","tracking_id"

"10","Alias","42","my list","13","jack@myemail.com","Jack","Sprat","2017-06-20 10:00:09","9","4456"
"10","Alias","42","my list","14","jane@myemail.com","Jane","Doe","2017-06-20 10:00:09","9","4457"

Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, and additional column "customer_key" will be included in the results.

Results

The Report Tracked Events commands output either the results of the search or a FAILURE message.

Success

The Report Tracked Events commands do not explicitly return a Success code. Instead, each outputs the data columns in CSV format with no header. Commands that support offset return 250 results at a time. The ALL versions of the commands return the first 5000 results.

Use the output_format argument to return the following data in an alternate format. Note the difference in output fields per each event type:

Column Name	Returned for
campaign_id	All Commands
campaign_alias	All Commands
list_id	All Commands
list_name	All Commands
subscriber_id	All Commands
email	All Commands
first_name	All Commands
last_name	All Commands
event_date	All Commands
event_type	Send, Unsub, Other
bounce_category	Delivery
meta_data	Other
url	Click
ip_address	Open ; Only displayed if version 17.11 or newer included in command.
user_agent	Open ; Only displayed if version 17.11 or newer included in command.
os_name	Open ; Only displayed if version 17.11 or newer included in command.
browser	Open ; Only displayed if version 17.11 or newer included in command.
client_type	Open ; Only displayed if version 17.11 or newer included in command.

NOTE: In some realms, tracking browser information for Opens and Clicks may not be permitted in order to honor privacy requirements in certain areas. These include IP Address, User Agent, OS Name, Browser, and Client Type. Please contact your Account Manager if you have questions.

Failure

A Report Tracked Events command will fail for several reasons, such as if the date is invalid or no data is found. The result format is:

FAILURE: [Reason]

Arguments

The Report Tracked Events commands support the following arguments:

Name	Req?	Description	Argument
Command	Yes	Defines the command to use: rpt_send_events rpt_api_send_events rpt_all_send_events rpt_open_events rpt_api_open_events rpt_all_open_events rpt_click_events rpt_api_click_events rpt_all_click_events rpt_delivery_events rpt_api_delivery_events rpt_all_delivery_events rpt_unsub_events rpt_tracking_other_events	cmd=[command] c=[command]
Realm	Yes	Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.	realm=[realm_name] r=[realm_name]
Password	Yes	Authentication code for API access. This is required, and the command will fail if the realm and password do not match.	pwd=[password] p=[password]
Start Date	Yes	Date to start reporting statistics	start_datetime=[mm/dd/yyyy%20hh:mm:ss]
End Date	Yes	Date to end reporting statistics	end_datetime=[mm/dd/yyyy%20hh:mm:ss]
Offset		The starting point from which to return results. The maximum result for each call is 250 contacts. For example, offset=0 returns the first 250 results, and offset=250 returns the next 250 results. Offset is in multiples of 250. Offset is not supported by the commands which return ALL (both campaign and one-off events), such as rpt_all_send_events .	offset=[0,250,500,etc.] DEFAULT==0
Limit Results		Limit the number of records returned from 1 to 5000, for commands that return ALL (both campaign and one-off events), such as rpt_all_send_events . In order to return more than 5000 events, you must break your commands up into the separate issues and go in batches of 250 using the offset argument.	limit=[1 to 5000] DEFAULT==5000
Output Format		To specify the format of the list output, use one of two arguments. If no argument is included, the default output is space-delimited plain text string, which may not include all data columns.	csv=1 or output_format=[csv,csv_tab, csv_pipe,xml]
Header		To define the data with a label, use the Header argument. This can only be used in conjunction with the output format, and does not affect XML.	headers=[0,1] DEFAULT==0
Version		Version of API to use. Data may be added to newer versions of the API. To alleviate issues for users who have already coded file parsing, new columns are only displayed if the version is included.	version=[version_number] 17.11 = for Open events only, display user_agent, ip, browser, os, and client/device type

*Feature released in v13.0.0.