For gathering data about the messages you're sending, the event webhooks are the recommended and most efficient replacement for the legacy Reporting API
So, what is a webhook?
Rather than using an API to request and pull your message data, a webhook is a programmatic way to receive instant notifications pushed directly to your application.
Getting Started with Event Webhooks
When are these changes being made?
Webhooks and the new SocketLabs API endpoints are available to use now.
The SocketLabs API (v2) is recommended for periodic data pulls whereas the event webhooks are intended for regular consumption of message events.
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.comCan 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.
However, the SocketLabs API (v2) works a little differently from it's legacy counterpart and all of the information associated with a message can be gathered in a single call. You no longer need to search for specific events. The below call will return all of the details for a particular message:
https://api.socketlabs.com/v2/servers/:serverId/reports/messages/detail?startDate=2022-01-01&endDate=2022-01-05&pageSize= 5&pageNumber=0&sortField=to&sortDirection=dsc
- MailingID, add: &filters=mailingId=eq:XX-XX-XXXXX
- To Address, add: &filters=to=eq:XXXX@example.com
Suppression API
| Action | Legacy API Call | SocketLabs API Call |
| DELETE | https://api.socketlabs.com/v1/suppressions?serverID=XXXXX&emailAddress=notauthorized@example.cns | 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?startDate=2022-01-01&endDate=2022-01-05&pageSize=5&pageNumber=0&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.
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 March 2024