©2009-2014 SocketLabs, Inc., Version 1.1, Last Edit: January 21, 2015
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 Configuration => Settings => Advanced Features => 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 Email On-Demand network. [▲]
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.
Helpful, Reliable and Affordable
Extremely Easy to Use, Could Not Be Happier
Best Deliverability Possible, Would Recommend to Anyone
Your Email Service ROCKS!!
Vastly Superior; Well Done!
Glad We Chose SocketLabs
Second to None, 5 Stars
We Love Your Service
You guys are great. Thank you.
Should Have Signed up Sooner
Fast & Reliable
Resolved All of Our Deliverability Issues!
We Have Never Looked Back
Responsive, Helpful, and Knowledgeable