SocketLabs On-Demand API Developer’s Guide
©2009-2014 SocketLabs, Inc., Last Edit: July 22, 2013
- Using the Email On-Demand API
Introduction to our APIs
The On-Demand API enables application developers and system integrators to interact with the SocketLabs 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. [▲]
- 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.
- 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.
- Receive real-time notifications for Engagement Tracking events, which consist of Open, Click, and Unsubscribe actions.
- Manage lists, which are used by our On-Demand marketing features.
- Manage individual contact data, which is used by our On-Demand marketing 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.
- Requested information represents the real-time state.
- Requested information can be retrieved in the JSON, JSONP, XML or CSV formats.
- 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.
Using the Email On-Demand API
- 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. [▲]
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. [▲]
- Injection API Documentation
- Notification API Documentation
- Inbound API Documentation
- Reporting API Documentation