Introduction to our APIs

The SocketLabs API suite enables application developers to interact with the SocketLabs platform programmatically

Our API suite provides real-time data upon request and supports the sending of outbound email via HTTP. In this documentation, we refer to separate segments of the suite based on what they do. 

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.


  • 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 .

Event Webhooks

Event Webhooks are 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.


  • 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.
    For technical reference, please see the Event Webhooks Documentation.

Marketing API

The Marketing API is for On-Demand customers who want to programmatically manage data (such as contact lists) used by our marketing features (such as Newsletters and Autoresponders).


  • Manage lists, which are used by our On-Demand marketing features.
  • Manage individual contact data, which is used by our On-Demand marketing features.
    For technical reference, please see the Marketing 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.


  • 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.

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.


  • 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.
    For technical reference, please see the Reporting API Documentation.

Suppression List API

The Suppression API is a REST API that allows you to programmatically search, add, or remove addresses from your server’s Suppression List. This API provides three methods.


  • GET - The GET method allows you to pass in a serverId and email address, and queries to see if the address exists on your server’s Suppression List.
  • POST - The POST method allows you to add an address to your Suppression List for the specified server (such as a customer unsubscribing).
  • DELETE - The DELETE method allows you to remove an email address from the Suppression List for the specified server (if it exists on the Suppression List for that server).
    For technical reference, definitions, and to build your code, please see the Suppression List API documentation

The Suppression List API is only available to Enterprise plan customers. If you are an Enterprise plan customer and would like access to this API, please contact our support team.


Best Practices Using the SocketLabs On-Demand API

Please follow these guidelines to the best of your ability when implementing any software that interacts with our APIs:

  • 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.

Technical Support for the APIs

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.

We are able to answer questions about the features and functionality of our API suite, as well as make recommendations about how best to use and integrate with our services.

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.