Monday, May 16, 2011

New Feature: Event API for Transactional Emails

We are excited to announce our newest feature: an event API for transactional emails. The transactional email event API is a system that can call any web service or web page on your server upon a specified transactional email event. The following transactional email events can trigger a call to your web service:
  1. A sent email
  2. An open of an email
  3. A click of a URL in an email
  4. An unsubscribe
  5. A bounce
  6. A complaint, via Feedback Loop
The transactional email event API is now offered in addition to our long-time existing broadcast email event API, which is covered in this PDF tutorial, this blog post for ASP.Net users, and this blog post for users who use a custom web service.

Why is the transactional email event API important?

You can now easily sync transactional email data with your own database or CRM system using the Event API. You only need one script on your web server to handle the calls from JangoMail. The calls are made in real-time when an event happens.

How do I set up an event-based web service call?

To set this up, go to Settings --> Integrating JangoMail with Other Systems --> Transactional Event API.  Click on the tab for each event for which you would like a web service called, and then enter the details for the web service.

What is the difference between the "Transactional Email Event API" and the "Standard API"?

The Standard API allows a programmer to interact with JangoMail much like a user would interact with JangoMail through the web-based interface. With the Standard API, you can pull reporting data, and send transactional email. The Event API pushes event data (opens, clicks, etc.) to your system when the event happens. The Standard API needs to be polled by your system to retrieve open or click data.

Some notes on this feature:
  1. If there are 1,000 consecutive failures when calling a specific web service for a specific event, then calls to the web service will cease until the URL or one of the parameters is modified. A failure is any HTTP response that is not status 200.
  2. When you first designate a web service and its attributes, JangoMail will call the web service for the last seven days worth of data. So if you specify a web service for the "open" event today, open data from the last seven days will immediately be posted to the web service.
  3. The parameter values will be URL-encoded before they are passed to your web service via HTTP POST or GET.
  4. You do not need to specify all parameters for a particular event. You only need to specify those parameters whose values you'd like your web service to receive.
  5. Every time JangoMail makes a call to your web service, it is recorded in the Event API Log, which can be viewed under Reports --> Logs --> Transactional Event API. From here you can see a list of all successful and failed calls to your web service.