Transactional Event API

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 can currently 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 Event API is a great way to make this happen.

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

There are two primary ways to access the settings for this feature.

If you're using JangoMail, you can find this feature in Settings → Integrating JangoMail with Other Systems → Transactional Event API.

If you're using JangoSMTP, you can find this feature in Settings → Advanced JangoSMTP Settings → Transactional Event API.

Please note that while this feature is listed in JangoMail, it only applies for Transactional messages.

Next, 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:

Let's take a look at a few specific sections of this tab.

First, you'll see a toggle to specify GET or POST.  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 box to the right of the GET or POST toggle.  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.

Here's a screenshot of a full configuration for Open:

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

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

Email Sent

Label Description Sample
Transactional Email ID 10 digit ID representing the message that was sent.

1234567890

User ID The numeric ID of the user account that sent the message. 123456
Email Address The destination address of the message that was sent. jane.dough@browniekitchen.com
Subject The subject line of the message that was sent. Check out our sweet deals! 
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Sent Date/Time The date and time that the message was sent. 

1/28/2015 9:19:00 AM

Open Track Enabled True if open tracking was enabled, False if not.  True
Click Track Enabled True if click tracking was enabled, False if not.  True
From Email Address The from address of the message that was sent. john.dough@browniekitchen.com
Message Size The numeric size of the message (in bytes) 784
Custom ID The custom header you've specified to capture in Settings.* 987987
RelayID The JangoMail / JangoSMTP Relay that accepted your message. RELAY-03
RelayMsgID The SMTP Message ID representing your SMTP transaction.

201501281650043324

Delivered False (currently unused) False

 

Open

Label Description Sample
User ID The numeric ID of the user account that sent the message.

123456

Transactional Email ID 10 digit ID representing the message that was sent. 1234567890
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Email Address The email address of the recipient who opened the message. jane.dough@browniekitchen.com
Open Date/Time The date and time that the message was opened.

1/28/2015 9:55:00 AM

IP Address The IP address of the recipient who opened the message. 123.123.123.123
Browser

The browser or email client the recipient used to open the message.

Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)
Custom ID The custom header you've specified to capture in Settings.*  987987

 

Click

Label Description Sample
User ID The numeric ID of the user account that sent the message. 123456
Transactional Email ID 10 digit ID representing the message that was sent. 1234567890
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Email Address The email address of the recipient who opened the message. jane.dough@browniekitchen.com
URL URL of the link that was clicked. http://www.browniekitchen.com
Position Numeric position of the clicked link.  Will be 1 unless the same link is specified multiple times in an email. 1
HTML True if the message body is HTML, False if it is plain text. True
Click Date/Time The date and time that the message was opened.

1/28/2015 9:56:00 AM

IP Address The IP address of the recipient who opened the message. 123.123.123.123
Browser

The browser or email client the recipient used to open the message.

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/600.2.5 (KHTML, like Gecko) Version/8.0.2 Safari/600.2.5

Custom ID The custom header you've specified to capture in Settings.* 987987

 

Unsubscribe

Label Description Sample
User ID The numeric ID of the user account that sent the message. 123456
Email Address The email address of the recipient who unsubscribed. jane.dough@browniekitchen.com
Unsubscribe Type If recipient clicked unsubscribe link, this value will be u.  If the recipient was manually added in the UI, API, or via a complaint, value will be m. u
Unsubscribe Date/Time The date and time that the unsubscribe was recorded.

1/28/2015 9:58:11 AM

IP Address The IP address of the recipient who unsubscribed. 123.123.123.123
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Transactional Email ID 10 digit ID representing the message that was sent. 1234567890
Custom ID The custom header you've specified to capture in Settings.* 987987

 

Bounce

Label Description Sample
User ID The numeric ID of the user account that sent the message. 123456
Email Address The email address of the recipient who bounced. jane.dough@browniekitchen.com
Bounce Date/Time The date and time that the bounce was recorded. 1/28/2015 10:45:11 AM
Diagnostic Code SMTP Diagnostic code returned by receiving server.

smtp;550 5.1.1 The email account that you tried to reach does not exist.

Definitive 1 if the bounce was definitive.  Any other number is non-definitive. 1
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Transactional Email ID 10 digit ID representing the message that was sent. 1234567890
Custom ID The custom header you've specified to capture in Settings.*  987987

 

Complaint

Label Description Sample
User ID The numeric ID of the user account that sent the message. 123456
Email Address The email address of the recipient who complained. jane.dough@browniekitchen.com
Complaint Date/Time The date and time that the complaint was recorded. 1/28/2015 10:13:11 AM
Abuse ID Internal numeric ID of the complaint. 12345678
Transactional Group ID The numeric ID of the Transactional Group associated with the message that was sent. 12345
Transactional Email ID 10 digit ID representing the message that was sent. 1234567890
Custom ID The custom header you've specified to capture in Settings.* 987987

 

 

* Custom ID

The Custom ID for the Event API refers to a custom header which you can include in your messages.  This header must be specified in the Settings for your account.

For JangoMail, this can be found in Settings → Transactional EmailsSMTP Relay → Custom-ID header.

For JangoSMTP, this can be found in Settings → Tracking → Custom-ID header.

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

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

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.

Last Updated: 1.28.2015 EP

Have more questions? Submit a request
Powered by Zendesk