SocketLabs Email On-Demand Notification API Guide

©2009-2014 SocketLabs, Inc., Version 1.1, Last Edit: February 11, 2014

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 notifications 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 => 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. [▲]

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 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 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. [▲]

Release Notes

Version 1.0, February 2013

  • Initial release.

Version 1.1, June 2013

  • The field ‘RemoteMTA’ has been renamed to ‘RemoteMta’.
  • The field ‘User-Agent’ has been renamed to ‘UserAgent’.
  • The ‘Tracking’ notification type has been added, which contains information about the Engagement Tracking events Open, Click, and Unsubscribe.

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

ResponseParameters:

SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
Type
Specifies the type of event. The value for this event is ‘Validation’.

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

Response Parameters:

Address
The email address this event is associated with.
DateTime
Specifies the date and time the complaint was generated. DateTime value is given according to the RFC 1123 format.
FblType
The type of report that has been processed. Currently the only supported value is “abuse”.
From
The from address that sent the feedback loop.
Length
The size, in bytes, of the feedback loop message that was processed.
MailingId
The custom Mailing ID of the original message being reported on.
MessageId
The custom Message ID of the original message being reported on.
SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
To
The to address that the feedback loop was sent to.
Type
Specifies the type of event. The value for this event is ‘Complaint’.
UserAgent
The user agent reported by the feedback loop.

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
  UserAgent = 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. 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. [▲]

Event Format Type:

application/x-www-form-urlencoded

HTTP Method:

POST

Response Parameters:

Address
The email address this event is associated with.
BounceStatus (If Available)
The status message set in the NDR, if available.
DateTime
Specifies the date and time the failure was generated. DateTime value is given according to the RFC 1123 format.
DiagnosticCode (If Available)
The diagnostic code set in the NDR, if available.
FailureCode
The reason for the failure, as enumerated in this KB article listing failure codes and reasons.
FailureType
The type of failure (0,1,2) for Soft Failures, Hard Failures, and Suppressed, respectively.
FromAddress (If Available)
The sender of the failed message.
MailingId
The custom Mailing ID of the original message being reported on.
MessageId
The custom Message ID of the original message being reported on.
Reason
A human readable explanation about why this message delivery failed.
RemoteMta
The remote mail exchange that the message was sent to.
SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
Type
Specifies the type of event. The value for this event is ‘Failed’.
Example:
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
  FromAddress = no-reply@example.com
  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

Response Parameters:

Address
The email address this event is associated with.
DateTime
Specifies the date and time the delivery was processed. DateTime value is given according to the RFC 1123 format.
LocalIp
The IP address used to deliver the message.
MailingId
The custom Mailing ID of the original message being reported on.
MessageId
The custom Message ID of the original message being reported on.
RemoteMta
The remote mail exchange that the message was sent to.
Response
The response from the remote server after accepting the message.
SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
Type
Specifies the type of event. The value for this event is ‘Delivered’.

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

Tracking

This event contains information about Engagement Tracking events. These include Opens, Clicks, and Unsubscribes. [▲]

Event Format Type:

application/x-www-form-urlencoded

HTTP Method:

POST

Response Parameters:

Address
The email address this event is associated with.
ClientIp
The IP address of the client which triggered the tracking event.
DateTime
Specifies the date and time the delivery was processed. 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.
SecretKey
The secret key as defined in the Control Panel.
ServerId
The Server ID this event is associated with.
TrackingType
The type of tracking event. This value is 0 for Click events, 1 for Open events, and 2 for Unsubscribe events.
Type
Specifies the type of event. The value for this event is ‘Tracking’.
Url
This is the URL involved in a Click event. For other event types this value should be empty.
UserAgent
The user agent reported by the tracking event.

Example:

PostBody:

  Type = Tracking
  DateTime = Mon, 01 Oct 2012 14:07:26 GMT
  MailingId = ""
  MessageId = ""
  Address = test@example.com
  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

Appendix

Downloadable Samples

Notification API sample code can be downloaded from github: http://github.com/socketlabs/ [▲]