JangoMail has an Event API feature that allows customers to have their own custom URL called when specific events occur within our system.  The events we act on include:

• A sent email
• An open of an email
• A click of a URL in an email
• An unsubscribe
• A bounce
• A complaint via Feedback Loop
• A block

If you want to be notified when any of these events occur, the Transactional Event API is a great way to make this happen. Note this feature is only applicable with Transactional messages.

This tutorial is an in-depth look at how to set up this feature, and what data to expect back from us.

• How to set up Transactional Event API
• Events included in Transactional Event API
• * Custom-ID Header
• Additional Info on Transactional Event API

How to set up Transactional Event API

To set up Transactional Event API, go to Settings → Notifications → Transactional Event API.

Let's look at an example of setting up this feature.  Once you've followed the instructions above to get to the settings, here's what you should see if you click on the Open tab:

First, you'll see a toggle to Enable events. Click to enable Transactional Event API for the OPEN event. 

Next, you'll see a toggle to specify GET, POST, or JSON.  This simply indicates how you'd prefer our system to pass the data to your specified URL.  For differences on GET vs POST, please see http://www.w3schools.com/tags/ref_httpmethods.asp.

Next, you'll see an empty field under URL. This is where you specify the URL that our system should use when sending the event data.  This URL should be able to accept the data from our end, and process it however you choose.

If you plan on capturing multiple types of events, you can either specify a different URL for each type, or use the same one, but specify a parameter specific to the action.  For example, if your URL is http://browniekitchen.com/handler.php, you could specify an event parameter, like this: http://browniekitchen.com/handler.php?event=open.

Finally, you'll see a list of boxes with labels. These are the individual parameters you want passed when a specific event occurs.  Any boxes that are left blank won't be passed to your URL. To enable a specific parameter, simply put the name you want it passed as in the box.

Once you've made your desired changes, click Save Event Settings.  The next time one of these events is triggered, we will send the data to you.

Events included in Transactional Event API

Now that we've covered how to set up a specific event, let's look at each event and the data returned: 

• Email Sent
• Open
• Click
• Unsubscribe
• Bounce
• Block
• Complaint

Email Sent

Open

Click

Unsubscribe

Bounce

Block

Complaint

* Custom-ID Header

The Custom-ID header for Transactional Event API refers to a custom header which you can include in your messages. The Custom-ID header is used with JangoMail reporting and Transactional Event API. This header must be specified in the Settings for your account.

This can be found in Settings → Transactional Settings → Relay → Custom-ID header.

In the box provided, specify the name of your custom header, like:

Once you specify this header and click Save Relay Settings, this will be used as the Custom ID if present in your message.

Additional Info on Transactional Event API

1. If there are 100 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 1 hour 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 → Toolbar → Logs → Transactional Event API. From here you can see a list of successful and failed calls to your web service.