SocketLabs Email On-Demand API Developer’s Guide

©2009-2013 SocketLabs, Inc., Last Edit: May 15, 2013

Index

Overview

Introduction to our APIs

The Email On-Demand API enables application developers and system integrators to interact with the SocketLabs Email On-Demand platform programmatically. Our API provides real-time data upon request, and supports the sending of outbound email via HTTP. In this documentation, we refer to separate segments of our API by name based on what they do. Following is a summary of the capabilities we currently provide via these APIs. [▲]

Reporting API

The Reporting API is for On-Demand customers who need to access statistics about their mail stream in scenarios where the more efficient Notification API is not appropriate.

Features

  • All requested information represents the real-time state.
  • All requested information can be retrieved in the JSON, JSONP, XML or CSV formats.
  • All requested information is read-only.
  • Retrieve account information including number of outbound messages injected, usage, allowances, etc.
  • Retrieve a list of every outbound email message that has failed, including the email address and reason. This includes both synchronous and asynchronous failures (bounces).
  • Retrieve a list of every feedback loop report (complaint) received, including the email address that generated the complaint.
  • Retrieve a list of each outbound message you have sent to your server for delivery.
  • Retrieve a list of each successfully sent outbound message.
  • Retrieve a list of each open or click event associated with an outbound message.
  • Identify the specific mailing and recipient associated with any event reported by the API.
For technical reference, please see the Reporting API Documentation. [▲]

Injection API

The Injection API is for On-Demand customers who need to send sets of related email messages utilizing our advanced merging functionality, or who prefer to send email via HTTP requests instead of SMTP.

Features

  • Construct outbound email messages in JSON or XML and inject them via a simple HTTP POST request.
  • Receive status information about each injection request in JSON or XML.
  • Send a single outbound email to multiple recipients in a single API call.
  • Send multiple outbound emails to multiple recipients in a single API call.
  • Perform on-the-fly mail merges in a single API call, using an arbitrary number of data fields.
For technical reference, please see the Injection API Documentation. [▲]

Notification API

The Notification API is for On-Demand customers who need to track the status of all messages sent through the On-Demand network by receiving real-time notifications about each and every message event. These events are posted to a user-defined endpoint via URL encoded HTTP POSTs, and can be stored and queried against locally in order to provide near real-time statistics and status information.

Features

  • Receive real-time notifications for Delivered events when outbound messages are successfully delivered.
  • Receive real-time notifications for Failed events when an outbound message cannot be delivered, including information indicating why the failure occurred.
  • Receive real-time notifications for Complaint events when recipients of outbound messages file spam complaints.
For technical reference, please see the Notification API Documentation. [▲]

Inbound API

The Inbound API is for On-Demand customers who need SocketLabs to parse one or more inbound mail streams, and to provide easy to process JSON messages to a user-defined endpoint. Each JSON message contains the parsed content of a single email, allowing easy integration of email content into business systems such as support desks, user forums, CRMs, and much more.

Features

  • SocketLabs’ On-Demand network processes one or more inbound mail streams, providing JSON messages containing the parsed-out email content.
  • Configure entire domains or individual addresses to be processed, parsed, and posted to a web application endpoint of your choosing.
For technical reference, please see the Inbound API Documentation. [▲]

Using the Email On-Demand API

Best Practices

  • While this document is meant to be comprehensive, do not assume that details not specifically mentioned in this document will not change. Changes to each API are listed in the release notes section of their respective pages. Please inform us if a feature or behavior could be documented better, so that this guide can be improved.
  • Always connect to our API using the DNS name and not the IP address. The IP address can change from time to time as we make changes to our infrastructure, perform maintenance, etc.
  • Responses from our API should not be considered case sensitive. In other words, if the case changes on a response, your code should be able to handle that.
  • Additional fields may be added to API responses and are considered to be backwards compatible. Do not write functionality that consumes API responses that cannot handle new or extraneous data fields.

Please follow these guidelines to the best of your ability when implementing any software that interacts with our APIs. [▲]

Technical Support

We are able to answer questions about the features and functionality of the API, as well as make recommendations about how best to use and integrate with our services. Before contacting our support staff, please be aware that we are not able to troubleshoot third-party software and code, or provide detailed information about how to work with REST, JSON, XML, HTTP, or any other technical protocol, library, or product. Only software developers comfortable working with these technologies should make use of our APIs, since we are only able to provide support to users assuming a baseline of technical knowledge.

As for resources, both simple examples and more complete code samples can be found on individual API documentation pages. If there are additional questions about our APIs, please create a support ticket through http://support.socketlabs.com/. Questions about purchasing and sales should be directed to our Sales department, which can be reached by phone or through our Contact Us form. [▲]

Detailed documentation for each of our APIs can be found at the following locations:
Samples and other code resources for our APIs can be found in our public Github code repository. [▲]