Service: GetEmailAddressHistory

The GetEmailAddressHistory service allows you to request a complete history or a history of a selection of actions for an email address. Default all actions will be selected. From the moment an emailAddressHistoryOptionsType is passed it will overrule the default setting.

Service Details

SOAP Action: GetEmailAddressesHistory
SOAP Return Object: GetEmailAddressHistoryResp

Input

The following table describes the parameters used for calling the GetEmailAddressHistory service.

Table: instance of GetEmailAddressHistoryReq

Parameter Mandatory Type Description
header Y APIRequestHeader Header for authentication
emailAddress Y String Email address to get the history for
timestampFrom / String Start history from this date
timestampTill / String Stop history at this date
emailAddressHistoryOptionsType / EmailAddressHistoryOptionsType Object to select which actions should be included in the history
sort / Integer Sort the results by time,default ASC
0 = ASC
1 = DESC

Output

The following table describes the parameters returned from the GetEmailAddressHistory service.

Table: instance of GetEmailAddressHistoryResp

Parameter Mandatory Type Description
header / APIResponseHeader Header containing authentication information
errorCode / Integer Numerical value of the error
errorMessage / String Short literal description of the error
emailAddressHistoryType / EmailAddressHistoryType The requested history

Table: response codes of GetEmailAddressHistoryResp.

0 No error
220 Authentication error, see header object for detailed information
221 Invalid email address

Example

This example shows how to request a complete history or a history of a selection of actions for an email address.

<?php
$header->userId = USER_ID;
$header->userToken = USER_TOKEN;

// create the new GetEmailAddressHistoryRequest
$request->header = $header;

// set the email address to request the history for
$request->emailAddress = "john.doe@example.com";

// optionally set a start time and or a stop stop
$request->timestampFrom = "2010-01-01T00:00:00";
$request->timestampTill = "2010-12-31T23:59:59";

// optionally create an options object to select the preferred actions
$options = new stdClass();
$options->campaignRead = true;
$options->campaignSent = true;
$options->linkClicked = true;

// add these options to the request
$request->emailAddressHistoryOptionsType = $options;

// execute the request
$response = $SoapClient->__soapCall("GetEmailAddressHistory", array($request));

// Check for errors
if ($response->errorCode == 0) {
	echo "History recieved email adddresses";

	foreach ($response->emailAddressHistoryType->emailAddressHistoryActionTypeItems as $action) {
		echo $action->actionId . "-" . $action->timestamp . "<br />";

		switch ($action->actionId) {
		case 17:
			echo "Sent campaign: " . $action->campaign->value . "<br/>";
			break;

		case 18:
			echo "Read campaign: " . $action->campaign->value . "<br />";
			break;

		case 20:
			echo "Clicked on a link:" . $action->link->value . "<br />";
			break;
		}
	}
} else {
	echo "Could not retrieve email address history: " . $response->errorMessage;
}
?>