SocketLabs Email On-Demand Notification API Guide
©2009-2013 SocketLabs, Inc., Version 1.0, Last Edit: April 29, 2013
Index
Notification API Overview
API Purpose
The Email On-Demand Notification API provides the ability to subscribe to automatically generated HTTP POST event notifications, which can be consumed by your own applications. 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 notificiations for every event is much more efficient than after-the-fact queries against our system via the Reporting API.
Authentication & Access
To enable this feature, visit the Configuration => Settings => Beta Features => HTTP 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 a notification receipt endpoint to live at a URL required by our configurations. This endpoint will need to both process and store the notification information as it comes in, 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.
Best Practices
When handling notification 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 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.
Error Handling & Rate Limiting
Once your endpoing is configured properly, there is no hard limit to the number of notifications you can receive. In the case where your endpoint becomes unresponsive, we may disable the notification feature on your account to prevent generating large numbers of notifications which cannot be delivered.
Release Notes
Version 1.0, February 2013
- Initial release.
Event Reference
Validation
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.
Event Format Type:
application/x-www-form-urlencoded
HTTP Method:
POST
Parameters:
- Type: Specifies the type of event. The value for this event is ‘Validation’.
- ServerId: The Server ID this event is associated with.
- SecretKey: The secret key.
Example:
PostBody: Type = Validation ServerId = 1000 SecretKey = YOUR-SECRET-KEY
Complaint
This event contains information about a Spam/Feedback Report generated when a user marked a delivered message as spam.
Event Format Type:
application/x-www-form-urlencoded
HTTP Method:
POST
Parameters:
- Type: Specifies the type of event. The value for this event is ‘Complaint’.
- DateTime: Specifies the date and time the complaint was generated. DateTime value is given according to the RFC 1123 format.
- MailingId: The custom Mailing ID of the original message being reported on.
- MessageId: The custom Message ID of the original message being reported on.
- Address: The email address this event is associated with.
- ServerId: The Server ID this event is associated with.
- SecretKey: The secret key.
- FblType: The type of report that has been processed. Currently the only supported value is “abuse”.
- User-Agent: The user agent reported by the feedback loop.
- From: The from address that sent the feedback loop.
- To: The to address that the feedback loop was sent to.
- Length: The size, in bytes, of the feedback loop message that was processed.
Example:
PostBody: Type = Complaint DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = test@example.com ServerId = 1000 SecretKey = YOUR-SECRET-KEY FblType = abuse User-Agent = Yahoo!-Mail-Feedback/1.0 From = test@example.com To = test@example.com Length = 495
Failed
This event contains information about a delivery failure, either temporary or permanent, for a single message. For reference, we provide a complete list of failure reasons and error codes.
Event Format Type:
application/x-www-form-urlencoded
HTTP Method:
POST
Parameters:
- Type: Specifies the type of event. The value for this event is ‘Failed’.
- DateTime: Specifies the date and time the complaint was generated. DateTime value is given according to the RFC 1123 format.
- MailingId: The custom Mailing ID of the original message being reported on.
- MessageId: The custom Message ID of the original message being reported on.
- Address: The email address this event is associated with.
- ServerId: The Server ID this event is associated with.
- SecretKey: The secret key.
- BounceStatus: The status message set in the NDR, if available.
- DiagnosticCode: The diagnostic code set in the NDR, if available.
- FailureCode: The reason for the failure, as enumerated in this list of failure reasons and codes.
- FailureType: The type of failure (0,1,2) for Hard Failures, Soft Failures, and Suppressed, respectively.
- Reason: A human readable explanation about why this message delivery failed.
- RemoteMTA: The remote mail exchange that the message was sent to.
PostBody: Type = Failed DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = test@example.com ServerId = 1000 SecretKey = YOUR-SECRET-KEY BounceStatus = 5.0.0 DiagnosticCode = smtp;550+Requested+action+not+taken:+mailbox+unavailable FailureCode = 2001 FailureType = 0 Reason = The email address is invalid RemoteMTA = mx1.example.com
Delivered
This event contains information about the successful delivery of a single message.
Event Format Type:
application/x-www-form-urlencoded
HTTP Method:
POST
Parameters:
- Type: Specifies the type of event. The value for this event is ‘Delivered’.
- DateTime: Specifies the date and time the complaint was generated. DateTime value is given according to the RFC 1123 format.
- MailingId: The custom Mailing ID of the original message being reported on.
- MessageId: The custom Message ID of the original message being reported on.
- Address: The email address this event is associated with.
- ServerId: The Server ID this event is associated with.
- SecretKey: The secret key.
- RemoteMTA: The remote mail exchange that the message was sent to.
- Response: The response from the remote server after accepting the message.
- LocalIp: The IP address used to deliver the message.
Example:
PostBody: Type = Delivered DateTime = Mon, 01 Oct 2012 14:07:26 GMT MailingId = m012 MessageId = 0000000155 Address = test@example.com ServerId = 1000 SecretKey = YOUR-SECRET-KEY RemoteMTA = mx1.example.com Response = 250 2.6.0 Message received and queued LocalIp = 255.255.255.255
Appendix
Downloadable Samples
A sample Notification API endpoint can be found in out public Github repository, located at:
