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. 

SocketLabs API

The SocketLabs API allows you to access SocketLabs configuration features programmatically, pull reporting data, and inject messages without having to login to the Control Panel.

Features

  • Manage and create multiple keys for account configuration and/or injecting messages for each server.
  • Add Sending Domains and configure DKIM signatures, Custom Bounce Domains and Engagement Tracking.
  • Pull Reporting Data

The SocketLabs API reporting feature is designed for one-off data pulls. The Event Webhook is for senders that need to regularly track the status of messages.

  • Suppression Function

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

Suppression functionality is a plan level feature.

Injection API

The Injection API is for 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.

Event Webhooks

Event Webhooks are for senders who need to track the status of all messages sent through the SocketLabs network by receiving real-time notifications about each and every message. Events are sent to a user defined URL endpoint that can receive and handle HTTP Post events.

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.
  • Receive real-time notifications for Engagement Tracking events, which consist of Open, Click, and Unsubscribe actions.

The Marketing API is for senders who want to programmatically manage data used by our Email Marketing Tools feature (such as Newsletters and Autoresponders).

Features

  • Manage lists and individual contact data

The Inbound API is for customers that 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’ 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.

Best Practices Using the SocketLabs 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.