API Reference (Reporting API)

SocketLabs On-Demand Reporting API Guide


Reporting API Overview

API Purpose

The SocketLabs On-Demand Email Reporting API provides users with the ability to query the system for most outbound-message-related information. Providing this information allows users to programmatically retrieve and store information about an account’s status and the status of outbound messages sent through said account. In this way, we enable users to build the tools they need in order to manage the use of our SocketLabs On-Demand services for their business.

This API is mostly succeeded by the Notification API, which allows users to receive and consume notifications about individual message delivery in real time. [▲]

Access & Authentication

The SocketLabs On-Demand API uses basic, standard HTTP authentication over SSL. Please refer to your development platform documentation for instructions on how to use HTTP authentication with REST calls. All calls to the API must be over HTTPS for security. Non-secure HTTP calls are not supported. Additionally, the email Reporting API operates on the account level while the Injection API operates on the virtual server level, so the required credentials for these functions are not the same.

Reporting API credentials exist on a per-user level. Therefore, your Reporting API username is the same as the username you use to log into the SocketLabs On-Demand control panel, and a Reporting API key is used as a password. In order to retrieve your email Reporting API key, log into your control panel and click your user name in the upper right hand corner of the screen. Your Reporting API key is automatically generated and cannot be edited for security reasons. You can regenerate this key, however, by clicking on the regenerate icon to the right of the Reporting API key.

Please be aware that if you change any of your API credentials, any application that uses old information will stop working until it is updated with the new credentials. [▲]

Data Retention and Availability

We currently retain data for ninety (90) days. Due to the amount of data stored for each of the millions of outbound messages sent through our system, we are currently unable to process API requests for information beyond this time period. [▲]

Release Notes

Version 1.0, February 2010

Version 1.1, March 2010

Version 1.2, April 2010

Version 1.3, November 2010

Version 1.4, February 2011

Version 1.5, February 2011

Version 1.6, May 2011

Version 1.7, April 2013

Version 1.8, January 2014

Version 1.9, October 2014

Future release notes will be added here.

Using the Reporting API

Best Practices

The Reporting API is able to retrieve specific details about each of potentially millions of outbound messages. It may be tempting to integrate the API into an application in such a way that a query is made for each outbound message any time information about that message is required. However, API calls should not repeatedly request information for large numbers of messages individually or continually. Instead, build your applications to query the API progressively in batches (i.e. via a data range) and store this data locally (i.e. in your own database), where it can be searched more frequently. This will reduce the number of required API queries, speed up your applications, and also provide you with greater data redundancy and availability.

If you wish to process information about each message individually, or receive information about message delivery in real time, then please take a look at our Notification API.[▲]

Error Handling & Rate Limiting

Your application should be designed to handle failure conditions such as receiving no response or an error response from our outgoing email servers. For example, the API may be down temporarily for maintenance, and calling applications should be able to handle such a situation gracefully.

Restrictions on using the Reporting API are as follows:

When querying the email Reporting API and one of these errors is encountered, a response in either JSON or XML is generated, with the following information:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

The ‘timestamp’ field is the date and time of the request. The ‘result’ field contains a description of the error encountered. Example result values are “Your request is being throttled, you are only allowed to make 70 requests per 00:01:00.” for throttling and “Your account has reached the limit for API requests, you will not be able to make any more requests until you contact us to resolve the issue.” for having reached a monthly API limitation. These strings may change in the future so do not program against the literal values. Finally, please be sure to design any application using this API to handle errors so that an appropriate action can be taken.[▲]


By default the Reporting API processes all dates and times as UTC (both input and output). Reporting API methods that process dates and times support an optional timeZone parameter which you can use to indicate that you would like to use an alternate timezone. The timeZone parameter should be your desired offset from UTC in minutes. So for example, if you are in PST (UTC-8), and want the data returned in your local time, you would pass a value of -480 for the timezone parameter (-8*60=-480). Any timezone specified will be applied to all input date/time parameters as well as all dates/times returned by the Reporting API. [▲]

Server Id

Each of the Reporting API methods take a server id as a parameter. The server id specifies which of the SocketLabs On-Demand servers you are accessing. Your server id can be found next to your server name in the SocketLabs On-Demand control panel. [▲]

Mailing IDs & Message IDs

The SocketLabs On-Demand system supports the use of “mailing ids” and “message ids”, which allow you to tag your outbound messages with user-defined identifiers that can then be used in the On-Demand Web Interface and the API. This is a powerful feature that enables you to track groups of messages or individual messages using identifiers that are meaningful to your application or organization.

Mailing Ids

Mailing Ids allow you to tag your outbound messages with a group identifier. This could be specific to a campaign, job, batch, or any grouping of messages. To tag your messages with a mailing id, a header must be specified in each of the email messages containing the mailing id.

The header name must be: X-xsMailingId

The header value may be: An alphanumeric value including 0-9, A-Z, a-z and hyphen.

Message Ids

Message Ids allow you to tag your outbound messages with a specific identifier. This identifier could be specific to the individual message, the recipient of a message, or any value that works for your application. To tag your messages with a message id you must specify a header in each of your email messages that contains the message id.

The header name must be: X-xsMessageId

The header value may be: An alphanumeric value including 0-9, A-Z, a-z and hyphen.

The following is an example of an RFC-822 formatted email message using both a message id and mailing id:

From: John Doe 
To: Sue Brooks 
Date: Sat, 21 Nov 2009 09:15:54 -0600
Subject: Giving Thanks
X-xsMailingId: Campaign-1
X-xsMessageId: FBC5747E24

This is the message body.

IMPORTANT: When an outbound message is sent by our system, the message id and mailing id values (if any) are encoded into the return path address using VERP. Since there are limitations to the size of an email address, the values you use should be as short as possible. It is highly recommended that you limit the message id and mailing id length to a total combined size of thirty (30) characters or less. [▲]

Method Reference


Returns basic server information including current usage statistics.
Method Documentation


Returns a list of email messages that failed during the delivery process due to either temporary or permanent errors.
Method Documentation


Retrieve a list of outbound email messages that have been sent to (queued by) the system.
Method Documentation


Retrieve a list of outbound email messages that have been successfully sent by the system.
Method Documentation


Retrieve a list of feedback loop reports, which represent spam complaints against previously delivered messages.
Method Documentation


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


Delivery Failure Codes

There are a set of failure codes that may be returned from the messagesFailed API method. The codes are grouped for convenience, and the current list is enumerated in the following KB article: https://support.socketlabs.com/kb/123. [▲]

Downloadable Samples

Reporting API sample code can be downloaded from github: http://github.com/socketlabs/ [▲]

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!