Report Contact Events allows you to return all tracking events of any type for a contact specified by either subscriber_id or email.
NOTE: As of revision 13.0.0, the rpt_subscriber_events command no longer supports returning all events in a single call. You must use the specific event type ID, found in Event Types.
The Report Contact Events command requires the following arguments: Command, Realm, Password, and Contact ID or Email.
api_web?r=myrealm&p=mypass&c=rpt_subscriber_events&subscriber_id=44956
The command is ‘rpt_subscriber_events’, the realm is ‘myrealm’ and the password is ‘mypass’. The events to return are for contact with id='44956'.
api_web?r=myrealm&p=mypass&c=rpt_subscriber_events&email=jane@domain.com
The events to return are for contact with email='jane@ domain.com'. If more than one contact exists with the same email address, then the first name is also required:
api_web?r=myrealm&p=mypass&c=rpt_subscriber_events&email=jane@domain.com&first=Jane
A successful search will return a list of events for the contact, the associated list and the event date.
Example
Using all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=rpt_subscriber_events&subscriber_id=298&event_type=21&output_format=csv&headers=1
Successful results return:
"Event","Event ID","List","List ID","Date"
"Unsubscribed","21","My List","5","09/26/12 11:02 AM"
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, you may use the customer_key to find a contact instead of email or identity_field:
api_web?r=myrealm&p=mypass&c=rpt_subscriber_events&customer_key=11293&event_type=21&output_format=csv&headers=1
Results
The Report Contact Events command outputs either the results of the search or a FAILURE message.
Success
The Report Contact Events command does not explicitly return a Success code. Instead, it outputs the campaign id, list name, subject, date sent, and number of recipients in plain text format. Use the output_format argument to return the results in an alternate format.
"Event","Event ID","List","List ID","Date"
Failure
A Report Contact Events command will fail for several reasons, such as if the contact doesn't exist. The result format is:
FAILURE: [Reason]
Arguments
The Report Contact Events command supports the following arguments:
Name |
Req? |
Description |
Argument |
Command |
Yes |
Defines the command to use. |
cmd=rpt_subscriber _events c=rpt_subscriber _events |
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] |
Contact ID |
* |
Identifier for the contact data to return. Required if Email is not defined. |
subscriber_id=[subscriber_id] |
* |
Email identifier for the contact data to return. Required if Contact ID is not defined. |
email=[email] | |
First Name | * |
First Name of the contact data to return. Required if contacts with the same email address exist. |
first=[first_name] |
Customer Key |
* |
Identifier of the contact to find in lieu of Email or Identity Field. Only available on some systems. |
customer_key=[customer_key] |
Event Type |
Identifier for the type of event to report. If not included, events of all types are returned. See Event Types. NOTE: event_type=0 is no longer valid as of v13.0.0 |
event_type=[event_type_id] | |
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 |
*Deprecated as of v13.0.0
Comments