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 | ||
| 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 |
| 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 |
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.