For Developers
      Back to home
      1. Help Center
      2. For Developers

      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