SocketLabs Email On-Demand Reporting API Guide
©2009-2013 SocketLabs, Inc., Version 1.6, Last Edit: May 15, 2013
Index
Reporting API Overview
API Purpose
The Email On-Demand Reporting API provides users with the ability to query the Email On-Demand 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 Email On-Demand services for their business. [▲]
Access & Authentication
The Email 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 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 Email On-Demand control panel, and a Reporting API key is used as a password. In order to retrieve your 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 (Show)
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. [▲]
Error Handling & Rate Limiting
Your application should be designed to handle failure conditions such as receiving no response or an error response from our API server. For example, the API may be down temporarily for maintenance, and calling applications should be able to handle such a situation gracefully.
The single existing restriction on the Reporting API is that it is limited to approximately one (1) call per second per API key.
Current restrictions with all aspects of the API may change to allow greater volume and speed in the future. [▲]
Timezones
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 Email On-Demand servers you are accessing. Your server id can be found next to your server name, in the SocketLabs Email On-Demand control panel. [▲]
Mailing IDs & Message IDs
The Email 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 Email 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
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
accountData
Returns basic server information including current usage statistics.
URL:
https://api.socketlabs.com/v1/accountData
Response Format Types:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id to query. If this parameter is omitted, then the information for the oldest server on the account will be returned.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
https://api.socketlabs.com/v1/accountData?serverid=1234&type=xml Response:
<response>
<timestamp>2009-11-21T13:57:11.1034784Z</timestamp>
<object>
<ServerId>1234</ServerId>
<CurrentBillingPeriodStart>2009-11-15T00:00:00Z</CurrentBillingPeriodStart>
<CurrentBillingPeriodEnd>2009-12-14T00:00:00Z</CurrentBillingPeriodEnd>
<BillingPeriodApiAccessCount>0</BillingPeriodApiAccessCount>
<BillingPeriodMessageCount>29588</BillingPeriodMessageCount>
<BillingPeriodByteCount>379656868</BillingPeriodByteCount>
<ServerApiAccessAllowance>0</ServerApiAccessAllowance>
<ServerMessageAllowance>1000000</ServerMessageAllowance>
<ServerByteAllowance>64000000000</ServerByteAllowance>
<IsOverAllowance>false</IsOverAllowance>
<IsOverByteAllowance>false</IsOverByteAllowance>
<IsOverMessageAllowance>false</IsOverMessageAllowance>
</object>
</response>
messagesFailed
Retrieves a list of outbound email messages that have failed, including the email address and type of failure. This includes both synchronous and asynchronous failures (bounces). See the Failure Codes section at the end of this document for a detailed list of the failure codes returned by this method. Please note, sometimes temporary failures are referred to as “soft” failures and permanent failures are referred to as “hard” failures. The terms are interchangeable. The SocketLabs Email On-Demand API marks failures as permanent if it believes that future delivery to that address is impossible. i.e. We received an “invalid address” response from the recipient’s mail server. These addresses should be corrected or removed from your list. The API marks failures as temporary if we believe that you many have luck delivering to that address in the future. i.e. Their mailbox was full. See the failureType parameter for more information.
URL:
https://api.socketlabs.com/v1/messagesFailed
Response Format Types:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id of the SocketLabs Email On-Demand server to access.
- startDate: (optional). Refers to the date and time that the outbound message failed. 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.
- endDate: (optional). Refers to the date and time that the outbound message failed. 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.
- timeZone: (optional). Specifies the timeZone offset that will be used by the API. See the section on Working with Timezones for more information.
- mailingId: (optional). Only records matching the specified mailingId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- messageId: (optional). Only records matching the specified messageId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- index: (optional). Specifies the zero based index of the first record to return from the result set.
- 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.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
https://api.socketlabs.com/v1/messagesFailed?serverId=1234&type=xml Response:
<response>
<timestamp>2010-03-25T15:55:49.6441608Z</timestamp>
<totalCount>2</totalCount>
<totalPages>1</totalPages>
<count>2</count>
<collection>
<item>
<ServerId>1000</ServerId>
<DateTime>2010-03-24T13:02:56Z</DateTime>
<MessageId/>
<MailingId/>
<ToAddress>me@raybushaw2.com</ToAddress>
<FromAddress/>
<FailureType>1</FailureType>
<FailureCode>2002</FailureCode>
<Reason>
Name service error for raybushaw2.com Type=A: Host not found
</Reason>
</item>
<item>
<ServerId>1000</ServerId>
<DateTime>2010-03-24T18:33:42Z</DateTime>
<MessageId/> <MailingId/>
<ToAddress>dmorrisetter@rayparamount.com</ToAddress>
<FromAddress/>
<FailureType>1</FailureType>
<FailureCode>2001</FailureCode>
<Reason>550 5.1.1 <dmorrisetter@rayparamount.com>: Recipient
address rejected: User unknown.</Reason>
</item>
</collection>
</response>
The FailureType in the response may be one of the following values: * 0 for soft/temporary failures * 1 for hard/permanent failures * 2 for suppressed messages. [▲]
messagesQueued
Retrieve a list of outbound email messages that have been sent to (queued by) the system.
URL:
https://api.socketlabs.com/v1/messagesQueued
Format:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id of the SocketLabs Email On-Demand server to access.
- startDate: (optional). Refers to the date and time that the outbound message entered the queue. 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.
- endDate: (optional). Refers to the date and time that the outbound message entered the queue. 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.
- timeZone: (optional). Specifies the timeZone offset that will be used by the API. See the section on Working with Timezones for more information.
- mailingId: (optional). Only records matching the specified mailingId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- messageId: (optional). Only records matching the specified messageId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- index: (optional). Specifies the zero based index of the first record to return from the result set.
- 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.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
https://api.socketlabs.com/v1/messagesQueued?serverId=1234&count=2&type=xml Response:
<response>
<timestamp>2009-11-29T13:51:22.1831066Z</timestamp>
<totalCount>364</totalCount>
<totalPages>182</totalPages>
<count>2</count>
<collection>
<item>
<ServerId>1000</ServerId>
<DateTime>2009-10-01T00:09:39Z</DateTime>
<MessageId/>
<FromAddress>jane@advanced-email.com</FromAddress>
<MailingId/>
<MessageSize>12327</MessageSize>
<ToAddress>user@gmail.com</ToAddress>
</item>
<item>
<ServerId>1000</ServerId>
<DateTime>2009-10-01T00:47:58Z</DateTime>
<MessageId/> <FromAddress>joe@advanced-email.com</FromAddress> <MailingId/>
<MessageSize>2497</MessageSize>
<ToAddress>user@gmail.com</ToAddress>
</item>
</collection>
</response>
messagesProcessed
Retrieve a list of outbound email messages that have been successfully sent by the system. Note: A message is considered “successfully sent” when it is accepted by the recipient’s mail server. This does not always mean that the message was delivered to the recipient’s inbox. The SMTP protocol does not provide a mechanism to determine what happens to a message after it has been accepted by the recipient’s mail server. Also, note that “successfully sent” outbound messages may bounce later, and if that happens, they will show in the results of the messagesFailed method.
URL:
https://api.socketlabs.com/v1/messagesProcessed
Format:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id of the SocketLabs Email On-Demand server to access.
- startDate: (optional). Refers to the date and time that the outbound message was processed. 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.
- endDate: (optional). Refers to the date and time that the outbound message was processed. 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.
- timeZone: (optional). Specifies the timeZone offset that will be used by the API. See the section on Working with Timezones for more information.
- mailingId: (optional). Only records matching the specified mailingId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- messageId: (optional). Only records matching the specified messageId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- index: (optional). Specifies the zero based index of the first record to return from the result set.
- 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.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
Retrieve the first two processed messages.
https://api.socketlabs.com/v1/messagesProcessed?serverId=1006&count=2&type=xml Response:
<response>
<timestamp>2009-11-29T15:58:05.8204122Z</timestamp>
<totalCount>1526</totalCount>
<totalPages>763</totalPages>
<count>2</count>
<collection>
<item>
<ServerId>1006</ServerId> <MessageId/>
<DateTime>2009-10-02T14:30:33Z</DateTime>
<Disposition>1</Disposition>
<FromAddress>steinitz@cox.net</FromAddress>
<LocalIp>192.168.100.117</LocalIp>
<MailingId/>
<MessageSize>20663</MessageSize>
<Response>250 ok: Message 1671124973 accepted{CRLF}</Response>
<ToAddress>askwalt@paypal.com</ToAddress>
</item>
<item>
<ServerId>1006</ServerId>
<MessageId/>
<DateTime>2009-10-02T21:15:46Z</DateTime>
<Disposition>1</Disposition>
<FromAddress>steinitz@cox.net</FromAddress>
<LocalIp>192.168.100.117</LocalIp>
<MailingId/>
<MessageSize>23547</MessageSize>
<Response>250 2.0.0 o1Fk1c021FmTw mail accepted for delivery{CRLF}</Response>
<ToAddress>steinitz@cox.net</ToAddress>
</item>
</collection>
</response>
messagesFblReported
Retrieve a list of feedback loop reports. The feedback loop system is a way for ISPs to provide feedback on the messages you send to recipients on their network. Most typically these are triggered as the result of a recipient clicking on the “report as spam” button in their email client, however feedback loops can also report other types of information. The “type” column in the result set will indicate the nature of the feedback, such as “abuse”. It is important that you remove email addresses from your list that have filed a complaint report against you. This can easily be accomplished by using the FeedbackLoops method to retrieve these addresses and then employ your own process to remove these from your list.
URL:
https://api.socketlabs.com/v1/messagesFblReported
Format:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id of the SocketLabs Email On-Demand server to access.
- startDate: (optional). Refers to the date and time that the feedback loop report was received. 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.
- endDate: (optional). Refers to the date and time that the feedback loop report was received. 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.
- timeZone: (optional). Specifies the timeZone offset that will be used by the API. See the section on Working with Timezones for more information.
- mailingId: (optional). Only records matching the specified mailingId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- messageId: (optional). Only records matching the specified messageId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- index: (optional). Specifies the zero based index of the first record to return from the result set.
- 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.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
Retrieve the feedback loop report data.
https://api.socketlabs.com/v1/messagesFblReported?serverId=1006&type=xml Response:
<response>
<timestamp>2009-11-29T22:43:35.6421962Z</timestamp>
<totalCount>2</totalCount>
<totalPages>1</totalPages>
<count>2</count>
<collection>
<item>
<ServerId>1000</ServerId>
<MessageId/>
<DateTime>2009-11-18T20:45:04Z</DateTime>
<FromAddress>staff@hotmail.com</FromAddress>
<MailingId/>
<OriginalRecipient>sooperhuggies@hotmail.com</OriginalRecipient>
<Type>abuse</Type>
<UserAgent>Hotmail</UserAgent>
</item>
<item>
<ServerId>1000</ServerId>
<MessageId/>
<DateTime>2009-11-18T22:45:03Z</DateTime>
<FromAddress>staff@hotmail.com</FromAddress>
<MailingId/>
<OriginalRecipient>nabiltohme@msn.com</OriginalRecipient>
<Type>abuse</Type>
<UserAgent>Hotmail</UserAgent>
</item>
</collection>
</response>
The Type in the response can be:
- abuse – spam or some other kind of email abuse
- dkim – a DKIM signature verification error
- fraud – indicates some kind of fraud or phishing activity
- virus – report of a virus found in the originating message
- other – any other feedback that doesn’t fit into other types
messagesOpenClick
Retrieve a list of open and click events for the outbound messages you have sent.
URL:
https://api.socketlabs.com/v1/messagesOpenClick
Format:
JSON, JSONP, XML or CSV
HTTP Method:
GET
Parameters:
- serverId: Specifies the server id of the SocketLabs Email On-Demand server to access.
- startDate: (optional). Refers to the date and time of the open or click event. 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.
- endDate: (optional). Refers to the date and time of the open or click event. 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.
- timeZone: (optional). Specifies the timeZone offset that will be used by the API. See the section on Working with Timezones for more information.
- mailingId: (optional). Only records matching the specified mailingId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- messageId: (optional). Only records matching the specified messageId will be returned. See the section on Using Mailing Ids & Message Ids for more information.
- index: (optional). Specifies the zero based index of the first record to return from the result set.
- 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.
- type: Specifies format of the response. May be set to JSON, JSONP, XML or CSV.
Example:
Retrieve the open and click data.
https://api.socketlabs.com/v1/messagesOpenClick?serverId=1006&type=xml Response:
<response>
<timestamp>2010-04-27T19:00:54.9388729Z</timestamp>
<totalCount>2</totalCount>
<totalPages>1</totalPages>
<count>2</count>
<collection>
<item>
<ServerId>1000</ServerId>
<DateTime>2010-03-01T16:29:57-04:00</DateTime>
<MessageId/> <MailingId/>
<OriginalRecipient>bing@socketlabs.com</OriginalRecipient>
<EventType>1</EventType>
<URL/>
<RemoteIp>173.161.212.25</RemoteIp>
</item>
<item>
<ServerId>1000</ServerId>
<DateTime>2010-03-01T16:30:00-04:00</DateTime>
<MessageId/>
<MailingId/>
<OriginalRecipient>bing@socketlabs.com</OriginalRecipient>
<EventType>0</EventType>
<URL>http://www.socketlabs.com</URL>
<RemoteIp>173.161.212.25</RemoteIp>
</item>
</collection>
</response>
Appendix
Delivery Failure Codes
The following failure codes may be returned from the messagesFailed API method. The codes are grouped for convenience. This list may be updated from time to time.
Message was rejected by recipient’s mail server:
1002-1003 Your message was rejected because it was associated with a blacklist
1004 Your message was rejected due to its content
1006 Too many connections in a period of time
1007 A virus was detected in your message
1010 Your message was rejected because the receiving server is not accepting mail
for the destination domain.
1999 Your message was rejected for a reason not specified above.
Recipient’s address is invalid (Permanent Error):
2001 The email address is invalid
2002 The domain of the email address is invalid
2003 The email address is not in a valid format
2004 The email address is no longer valid
2999 The email address was rejected for a reason not specified above
Delivery to the recipient’s address is temporarily unavailable (Temporary Error) :
3001 The recipient's mailbox is full or over quota
3002 Recipient email account is inactive/disabled
3003 Recipient’s server continuously asked us to “try later”
3999 The email address was rejected for a reason not specified above
System, network or protocol errors preventing delivery:
4001 Recipient’s server too busy
4002 Protocol error, invalid command or timeout
4003 Unable to connect to recipient's mail server
4004 Recipient’s server rejected message as too old
4006 Your message was rejected because the receiving server is not accepting
mail for the destination domain
4999 A system, network or protocol error prevented the delivery of your message
for a reason not specified above
Informational, we received a reply of the following type:
5001 Out of office / Auto-reply 5999 - An informational message was received
other than for a reason specified above
Unknown:
9999 The reason for the failure is unknown.
Downloadable Samples
Reporting API code samples in a variety of development languages can be downloaded from github: http://github.com/socketlabs/ [▲]
