Reporting API and Suppression API to SocketLabs API Migration Guide

We’re moving from Reporting API (Legacy) and Suppression API (Legacy) to SocketLabs API (Version 2). The SocketLabs API has expanded capabilities, improved security, and provides more information than ever before.

When are these changes being made? 

The new SocketLabs API endpoints are available to use now. 

The Reporting API and Suppression API will be decommissioned at the end of February 2024

Authentication Changes

There was a separate API key to access the Reporting and Suppression API, based on credentials in your user profile. In the SocketLabs API, those are combined to use the SocketLabs API key. For more information on authenticating to the SocketLabs API, please see Getting Started: Create an API Key.

ServerId Parameter Usage

In the legacy APIs, it required the serverId as a parameter in the URL, so you'd have something like https://api.socketlabs.com/v1/suppressions?serverId=XXXXX&emailAddress=example@example.com

In the SocketLabs API, the server ID is in the base URL, so that same call would look like: api.socketlabs.com/v2/servers/XXXXX/suppressions?emailAddress=recipient@example.com

Can you provide a mapping between the Legacy API calls and the SocketLabs API calls and what’s new?

Certainly! A table of the calls can be found below.

Suppression API

Action Legacy API Call SocketLabs API Call
DELETE https://api.socketlabs.com/v1/suppressions=notauthorized@example.cns?serverId=XXXXX&emailAddrom https://api.socketlabs.com/v2/servers/XXXXX/suppressions/remove?emailAddress=test@example.com
POST https://api.socketlabs.com/v1/suppressions?serverId=XXXXX&emailAddress=notauthorized@example.com https://api.socketlabs.com/v2/servers/XXXXX/suppressions?emailAddress=test@example.com
GET (one) https://api.socketlabs.com/v1/suppressions?serverId=XXXXX&emailAddress=example@example.com https://api.socketlabs.com/v2/servers/XXXXX/suppressions?emailAddress=recipient@example.com
GET (list based on provided search) Does not exist https://api.socketlabs.com/v2/servers/XXXXX/suppressions/search?pageSize=5&pageNumber=0&sortField=emailAddress&sortDirection=dsc
GET (download a list of addresses based on provided search terms) Does not exist https://api.socketlabs.com/v2/server/XXXXX/suppressions/download?sortField=suppressionLastUpdate&sortDirection=dsc

 

Reporting API

Action Legacy API Call SocketLabs API Call
GET Failed Messages* https://api.socketlabs.com/v1/messagesFailed?serverid=XXXXX&type=json&count=1&index=0&mailingId=MailingId-01&messageId=MessageId-01&startDate=01-01-2022&endDate=01-02-2022&timeZone=-240 https://api.socketlabs.com/v2/servers/XXXXX/reports/message/?pageSize=5&pageNumber=0&sortField=failTime&sortDirection=asc&startDate=2022-01-14&endDate=2022-01-14&type=Failures
GET Queued Messages (Get all Messages) https://api.socketlabs.com/v1/messagesQueued?serverid=XXXXX&type=json&count=1&index=0&mailingId=MailingId-01&messageId=MessageId-01&startDate=01-01-2022&endDate=01-02-2022&timeZone=-240 https://api.socketlabs.com/v2/servers/XXXXX/reports/message/?pageSize=5&pageNumber=0&sortField=queuedTime&sortDirection=asc&startDate=2022-01-14&endDate=2022-01-14
GET Processed Messages https://api.socketlabs.com/v1/messagesProcessed?serverid=XXXXX&type=json&count=1&index=0&mailingId=MailingId-01&messageId=MessageId-01&startDate=01-01-2022&endDate=01-02-2022&timeZone=-240 https://api.socketlabs.com/v2/servers/XXXXX/reports/message/?pageSize=5&pageNumber=0&sortField=sendTime&sortDirection=asc&startDate=2022-01-14&endDate=2022-01-14&type=Delivered
GET Message Complaints https://api.socketlabs.com/v1/messagesFblReported?serverid=XXXXX&type=json&count=1&index=0&mailingId=MailingId-01&messageId=MessageId-01&startDate=01-01-2022&endDate=01-02-2022&timeZone=-240 https://api.socketlabs.com/v2/servers/XXXXX/reports/message/?pageSize=5&pageNumber=0&sortField=FirstComplaint&sortDirection=asc&startDate=2022-01-14&endDate=2022-01-14&type=Complaints
GET Message Suppressed Does not exist https://api.socketlabs.com/v2/servers/XXXXX/reports/message/?pageSize=5&pageNumber=0&sortField=queuedTime&sortDirection=asc&startDate=2022-01-14&endDate=2022-01-14&type=Suppressed
GET Engagement Events https://api.socketlabs.com/v1/messagesOpenClick?serverid=XXXXX&type=json&count=1&endDate=01-02-2022&index=0&mailingId=12345&messageId=55555&startDate=01-01-2022&timeZone=-240 https://api.socketlabs.com/v2/servers/XXXXX/reports/messages/tracking/engagement/detail?startDate=2022-01-01&endDate=2022-01-05&pageSize=5&pageNumber=1&sortField=to&sortDirection=dsc

*Suppressed emails will no longer show in the failed messages call and can be pulled using one of the GET calls for Suppression listed above.

To search for a specific MailingID, add: &filters=mailingId=eq:XX-XX-XXXXX

For more information about the expanded SocketLabs API capabilities, visit our documentation: SocketLabs API

The Reporting API and Suppression API will be decommissioned at the end of February 2024