---
title: Reporting API and Suppression API Migration Guide
description: For gathering data about the messages you're sending, the event webhooks are the recommended and most efficient replacement for the legacy Reporting API
---
[Skip to content](https://help.socketlabs.com/docs/api-migration#main-content)
English
Show submenu for translations
[Contact us](https://help.socketlabs.com/docs/kb-tickets/new?hsLang=en)
[](https://www.socketlabs.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Contact us](https://help.socketlabs.com/docs/kb-tickets/new)
SocketLabs is here to help!
- There are no suggestions because the search field is empty.
1. [Help Center](https://help.socketlabs.com/docs?hsLang=en)
2. [For Developers](https://help.socketlabs.com/docs/for-developers?hsLang=en)
# Reporting API and Suppression API Migration Guide
## 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?](https://www.socketlabs.com/blog/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
- [Authentication and Access](https://help.socketlabs.com/docs/event-webhooks-authentication-and-access?hsLang=en)
- [Events](https://help.socketlabs.com/docs/event-webhooks-events?hsLang=en)
- [Data Attributes](https://help.socketlabs.com/docs/event-webhooks-data-attributes?hsLang=en)
### 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.](https://docs.socketlabs.com/#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.
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
Helpful filters:
- 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](https://docs.socketlabs.com/#getting-started-create-an-api-key)
The Reporting API and Suppression API will be decommissioned at the end of March 2024
- [Fundamentals](https://help.socketlabs.com/docs/fundamentals?hsLang=en#main-content)
- [StreamScore](https://help.socketlabs.com/docs/fundamentals?hsLang=en#streamscore)
- [Reports](https://help.socketlabs.com/docs/fundamentals?hsLang=en#reports)
- [Frequently Asked Questions](https://help.socketlabs.com/docs/fundamentals?hsLang=en#frequently-asked-questions)
- [Advanced](https://help.socketlabs.com/docs/advanced?hsLang=en#main-content)
- [Security](https://help.socketlabs.com/docs/advanced?hsLang=en#security)
- [DNS Authentication](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#main-content)
- [DKIM](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#dkim)
- [SPF and Custom Bounce Domain](https://help.socketlabs.com/docs/dns-authentication?hsLang=en#spf-and-custom-bounce-domain)
- [Deliverability](https://help.socketlabs.com/docs/deliverability?hsLang=en)
- [For Developers](https://help.socketlabs.com/docs/for-developers?hsLang=en#main-content)
- [Event Webhooks](https://help.socketlabs.com/docs/for-developers?hsLang=en#event-webhooks)
- [Integrations](https://help.socketlabs.com/docs/integrations?hsLang=en#main-content)
- [Languages and Frameworks](https://help.socketlabs.com/docs/integrations?hsLang=en#languages-and-frameworks)
- [Mail Servers](https://help.socketlabs.com/docs/integrations?hsLang=en#mail-servers)
- [Web Clients and Plug-ins](https://help.socketlabs.com/docs/integrations?hsLang=en#web-clients-and-plug-ins)
- [Mail Clients](https://help.socketlabs.com/docs/integrations?hsLang=en#mail-clients)
- [Marketing Tools](https://help.socketlabs.com/docs/marketing-tools?hsLang=en#main-content)
- [Tips and Tricks](https://help.socketlabs.com/docs/marketing-tools?hsLang=en#tips-and-tricks)
- [Troubleshooting](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#main-content)
- [SocketLabs Inbound SMTP Gateway Errors](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#socketlabs-inbound-smtp-gateway-errors)
- [SocketLabs Outbound SMTP Errors](https://help.socketlabs.com/docs/troubleshooting?hsLang=en#socketlabs-outbound-smtp-errors)
- [Spotlight Email Analytics](https://help.socketlabs.com/docs/spotlight-email-analytics?hsLang=en)
- [Hurricane MTA](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#main-content)
- [Advanced Hurricane Usage](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#advanced-hurricane-usage)
- [Upgrading Hurricane](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#upgrading-hurricane)
- [Troubleshooting](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#troubleshooting)
- [Hurricane Maintenance](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#hurricane-maintenance)
- [Getting Started with Hurricane](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#getting-started-with-hurricane)
- [Basic Hurricane Usage](https://help.socketlabs.com/docs/hurricane-mta?hsLang=en#basic-hurricane-usage)
- [Complex Sender](https://help.socketlabs.com/docs/complex-sender?hsLang=en)
[](https://www.socketlabs.com)
Copyright © 2026, SocketLabs LLC