API Reference – Reporting API – messagesOpenClick()

Reporting API Method Documentation

©2009-2014 SocketLabs, Inc., Version 1.9, Last Edit: October 24, 2014

messagesOpenClick

Synopsis:

Retrieve a list of open and click events for the outbound messages that have been sent.

Recommended Usage:

The messagesOpenClick method is deprecated in favor of the Notification API whenever possible. If the Notification API cannot be used, the messagesOpenClick method is useful for monitoring some engagement tracking events. Only the Open and Click events are available in both the Reporting API and the Notification API. The Unsubscribe event is only supported in the Notification API.

The messagesOpenClick method can be useful for tracking open and click events from delivered messages. One use for this method would be to store data in order to generate custom open and click tracking reports on delivered messages. This enables a user to have options beyond what is already available in the Email On-Demand control panel, such as being able to generate reports for older data which is no longer available through the control panel.

Request Information

URL:

https://api.socketlabs.com/v1/messagesOpenClick

Response Format Types:

JSON, JSONP, XML or CSV

HTTP Method:

GET

Request Parameters:

serverId
Specifies the server ID to query. For more information see this overview on using the Server ID.
type
Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
count
(Optional) Specifies the number of records to return in the result set. If this parameter is not specified it will default to 500. 500 is the maximum number of records that you may retrieve in one call. You can use this parameter in combination with the index parameter to pull down multiple “pages” of data making it possible to retrieve more than 500 records with multiple calls.
endDate
(Optional) Refers to the date and time that the open or click event occurred. Specifies the ending date and time of the records to return. The value should be formatted as yyyy-mm-dd hh:mm:ss. If the time is omitted it will default to 00:00:00.
index
(Optional) Specifies the zero based index of the first record to return from the result set.
mailingId
(Optional) Only records matching the specified mailingId will be returned. For more information see this overview on using Mailing ID and Message ID.
messageId
(Optional) Only records matching the specified messageId will be returned. For more information see this overview on using Mailing ID and Message ID.
startDate
(Optional) Refers to the date and time that the open or click event occurred. Specifies the starting date and time of the records to return. The value should be formatted as yyyy-mm-dd hh:mm:ss. If the time is omitted it will default to 00:00:00.
timeZone
(Optional) Specifies the timeZone offset that will be used by the API. For more information see this overview on using timezone data.

Example Request:

https://api.socketlabs.com/v1/messagesOpenClick?serverId=0001&type=xml

Response Data Structures

Response Data Structure (JSON):

{
    "timestamp": "Datetime",
    "totalCount": "Integer",
    "totalPages": "Integer",
    "page": "Integer",
    "count": "Integer",
    "collection": [
        {
            "ServerId": "Integer",
            "DateTime": "Datetime",
            "MessageId": "String",
            "MailingId": "String",
            "OriginalRecipient": "String",
            "EventType": "Integer",
            "Url": "String",
            "RemoteIp": "String"
        },
    ]
}

Response Data Structure (XML):

<response>
    <timestamp>Datetime</timestamp>
    <totalCount>Integer</totalCount>
    <totalPages>Integer</totalPages>
    <page>Integer</page>
    <count>Integer</count>
    <collection>
        <item>
            <ServerId>Integer</ServerId>
            <DateTime>Datetime</DateTime>
            <MessageId>String</MessageId>
            <MailingId>String</MailingId>
            <OriginalRecipient>String</OriginalRecipient>
            <EventType>Integer</EventType>
            <Url>String</Url>
            <RemoteIp>String</RemoteIp>
        </item>
    </collection>
</response>

Response Data Structure (CSV):

Data columns in the CSV format are in the following order:

ServerId,DateTime,MessageId,MailingId,OriginalRecipient,EventType,Url,RemoteIp

Response Parameters

count
The number of entries in this page of data.
page
The current page of data returned by the query.
timestamp
The date and time of the API request.
totalCount
This field is deprecated, and should return as 0.
totalPages
This field is deprecated, and should return as 0.
collection.item.DateTime
The date and time that the event occurred.
collection.item.EventType
Whether the event is a Click (0), Open (1) or an Unsubscribe (2) .
collection.item.MailingId
The X-xsMailingId header value of the message in question.
collection.item.MessageId
The X-xsMessageId header value of the message in question.
collection.item.OriginalRecipient
The original recipient of the message in question.
collection.item.RemoteIp
The IP address of the individual that triggered the open or click event.
collection.item.ServerId
The ID of the server being queried.
collection.item.Url
The URL used in a Click event. This is an empty string for Open events.

Response Examples

Example Response (JSON):

{
    "timestamp": "1368648632784",
    "totalCount": 0,
    "totalPages": 0,
    "page": 1,
    "count": 2,
    "collection": [
        {
            "ServerId": 0001,
            "DateTime": "1360886931000",
            "MessageId": "12345",
            "MailingId": "Campaign4",
            "OriginalRecipient": "[email protected]",
            "EventType": 1,
            "Url": "",
            "RemoteIp": "10.10.10.10"
        },
        {
            "ServerId": 0001,
            "DateTime": "1360888198000",
            "MessageId": "12353",
            "MailingId": "Campaign4",
            "OriginalRecipient": "[email protected]",
            "EventType": 0,
            "Url": "http://www.google.com/",
            "RemoteIp": "10.10.10.10"
        }
    ]
}

Example Response (XML):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<response>
    <timestamp>2013-05-15T20:10:03.8291459Z</timestamp>
    <totalCount>0</totalCount>
    <totalPages>0</totalPages>
    <page>1</page>
    <count>2</count>
    <collection>
        <item>
            <ServerId>0001</ServerId>
            <DateTime>2013-02-15T00:08:51Z</DateTime>
            <MessageId>12345</MessageId>
            <MailingId>Campaign4</MailingId>
            <OriginalRecipient>[email protected]</OriginalRecipient>
            <EventType>1</EventType>
            <Url></Url>
            <RemoteIp>10.10.10.10</RemoteIp>
        </item>
        <item>
            <ServerId>0001</ServerId>
            <DateTime>2013-02-15T00:29:58Z</DateTime>
            <MessageId>12353</MessageId>
            <MailingId>Campaign4</MailingId>
            <OriginalRecipient>[email protected]</OriginalRecipient>
            <EventType>0</EventType>
            <Url>http://www.google.com/</Url>
            <RemoteIp>10.10.10.10</RemoteIp>
        </item>
    </collection>
</response>

Example Response (CSV):

ServerId,DateTime,MessageId,MailingId,OriginalRecipient,EventType,Url,RemoteIp
0001,"""2/15/2013 12:08:51 AM +00:00""",12345,Campaign4,[email protected],1,,10.10.10.10
0001,"""2/15/2013 12:29:58 AM +00:00""",12353,Campaign4,[email protected],0,"http://www.google.com/",10.10.10.10

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!