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.
SOAP Action: GetEmailAddressesHistory
SOAP Return Object: GetEmailAddressHistoryResp
The following table describes the parameters used for calling the GetEmailAddressHistory service.
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 |
The following table describes the parameters returned from the GetEmailAddressHistory service.
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 |
0 | No error |
---|---|
220 | Authentication error, see header object for detailed information |
221 | Invalid email address |
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; } ?>