The Notification API provides the ability to subscribe to automatically generated HTTP POST event notifications, which can be consumed by your own applications. This type of API is also commonly referred to as a “webhook” API. Notifications are generated for SMTP events such as delivered messages, failed messages, and FBL messages received. This API makes it easy to receive real-time notification of these events, written in any language, on any platform, in any location, without the need to write traditional plugins. We recommend the use of the Notification API over the Reporting API whenever possible, as the receipt of real-time notifications for every event is much more efficient than after-the-fact queries against our system via the Reporting API. [▲]
To enable this feature, visit the “For Developers” dropdown menu in the SocketLabs On Demand Control Panel, select the “Configure Notification API” page and enable both the feature and the types of events you want to receive notifications from. Additionally, you will need to write and deploy an endpoint that can process and respond to notifications. The URL of this endpoint is required by this feature’s configuration. This endpoint will need to both process and store notifications as they arrive, as well as respond to our service with the proper authentication information. All notifications sent from our services will contain the Secret Key seen on the control panel page as well as your server ID, which should be used to ensure that all notifications are coming from our services. All responses to notifications need to contain the Validation Key, so that we continue to ensure that your endpoint is both identified and currently able to process notifications. We also ask that if the Secret Key does not match in a notification message, your application should return a 401 error response. [▲]
When handling delivery notification email messages, your applications should be able to handle additional, undocumented values in the PostBody as we may add additional attributes in future versions of this notification API. We also highly recommend storing all notification data received via this API in a local database so that your local applications can query and access this data as needed in an efficient and timely manner. Finally, the Notification API is recommended over the Reporting API, as it is both more timely and more efficient for both end users and the SocketLabs On-Demand network. [▲]
Some of the values contained in the PostBody may include data obtained from third-party mail servers and web browsers. SocketLabs will provide this data AS IS in the PostBody, therefore it is important to treat this data as untrusted. If you are storing data from the PostBody in your database, it is important to use prepared statements and/or parameterized queries in order to prevent potential injection attacks. Similarly, if you will be displaying this data to end users, it is important to make sure the data is encoded and/or escaped in order to avoid potential cross-site scripting or code execution.
Although unencrypted HTTP communication is allowed for your Notification API endpoint, it is strongly encouraged that you use HTTPS for your endpoint. Using unencrypted HTTP can pose a number of security risks. By the nature of the data being transmitted, Notification API-related calls made to your endpoint contain your SocketLabs server ID and Secret Key, as well as PII (Personally Identifiable Information) belonging to end-users, such as email address and IP address. Insecure transfer of such data over HTTP may pose data security risks (i.e.: confidentiality and integrity).[▲]
Once your endpoint is configured properly, there is no hard limit to the number of notifications you can receive. If an endpoint is temporarily unavailable due to a system outage on our end, your end, or somewhere between — all notifications will be queued up for another delivery attempt in exactly the same way as email deferral works. Notification API messages will be not be permanently failed and lost unless no contact can be made for at least four days.
In the case where your endpoint becomes unresponsive for long periods of time, we may disable the notification feature on your account to prevent generating large numbers of notifications which cannot be delivered. We would notify a user via email if this occurred, and the feature would need to be reconfigured via the control panel in order to be reactivated. [▲]
This event is used for validating the endpoint that will receive POST events. It should be responded to with a message containing the Validation Key. [▲]
PostBody: Type = Validation ServerId = 1000 SecretKey = YOUR-SECRET-KEY
This event contains information about a Spam/Feedback Report generated when a user marked a delivered message as spam. [▲]
PostBody: Type = Complaint DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = [email protected] ServerId = 1000 SecretKey = YOUR-SECRET-KEY FblType = abuse UserAgent = Yahoo!-Mail-Feedback/1.0 From = [email protected] To = [email protected] Length = 495
This event contains information about a delivery failure, either temporary or permanent, for a single message. Please be aware that three fields in this notification are not always present. These are FromAddress, BounceStatus, and DiagnosticCode. For reference, see the KB article containing a complete list of failure codes and reasons. [▲]
PostBody: Type = Failed DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = [email protected] ServerId = 1000 SecretKey = YOUR-SECRET-KEY BounceStatus = 5.0.0 FromAddress = [email protected] DiagnosticCode = smtp;550+Requested+action+not+taken:+mailbox+unavailable FailureCode = 2001 FailureType = 0 Reason = The email address is invalid RemoteMta = mx1.example.com
This event contains information about the successful delivery of a single message. [▲]
PostBody: Type = Delivered DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = [email protected] ServerId = 1000 SecretKey = YOUR-SECRET-KEY RemoteMta = mx1.example.com Response = 250 2.6.0 Message received and queued LocalIp = 255.255.255.255
This event contains information about Engagement Tracking events. These include Opens, Clicks, and Unsubscribes. [▲]
PostBody: Type = Tracking DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = "" MessageId = "" Address = [email protected] ServerId = 1000 SecretKey = YOUR-SECRET-KEY ClientIp = 127.0.0.1 TrackingType = 0 Url = http://www.socketlabs.com/ UserAgent = Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.110 Safari/537.36
You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.
Glad We Chose SocketLabs
Helpful, Reliable and Affordable
You … Are … The … Bomb!
We Have Never Looked Back
The customer service for SocketLabs is absolutely incredible.
Extremely Easy to Use, Could Not Be Happier
I love SocketLabs!
Resolved All of Our Deliverability Issues!
Customer Service is the reason for success
Your Email Service ROCKS!!
We Love Your Service
Responsive, Helpful, and Knowledgeable
Best Deliverability Possible, Would Recommend to Anyone
Fast & Reliable
Using a service such as SocketLabs helps us ensure that our business clients can get their email where it needs to be.
Knowledgeable… USA Built and Supported… Trusted IP Address
You guys are great. Thank you.
Should Have Signed up Sooner
I chose to use you over other services because …