Overview

Integration

User guide

API reference

Webhooks

Open tracking webhook

What is an open webhook?

When you send an email with open tracking, Postmark will store information when the recipient first opens and reads that email. Postmark displays that information in the Postmark application for your server. You can also pull the message opens using the API. For some applications, it’s easier to set a webhook URL for Postmark to push the data to your application as soon as Postmark gets it. An open webhook can instantly notify your application of message opens by POSTing the data in a JSON document to the webhook URL that you specify.

To know every time a recipient opens an email, you need to use the open webhook. If a recipient opens an email multiple times, Postmark will only save the first open. This is what is displayed on the Postmark website and queried through the message opens API. When the open webhook is saved with PostFirstOpenOnly set to false Postmark will POST the open information to your webhook URL every time an open occurs. This is the only way to get information about every open that occurs.

Set the webhook URL

The opens webhook URL is a server setting. You can only have one open webhook URL per server.

Using the Postmark website

When logged into Postmark, select the server and go to the “Settings” tab. The “Opens Webhook” field is where you should input your webhook URL. There is also a checkbox labeled “Post only on first open” to determine whether to send all opens or only the first open to your webhook.

Using the API

You can modify the OpenHookUrl field using the Servers API to modify existing servers. You can also use the Servers API to create servers and set the OpenHookUrl field at the same time. The PostFirstOpenOnly field (defaults to false) is used to determine whether to send all opens or only the first open to your webhook.

Open webhook data

An example of the full JSON document that would be POSTed to your webhook URL is to the right.

  • Recipient—the email address of the recipient who opened the email.
  • FirstOpen—if this open was the first time the recipient opened this email.
  • ReadSeconds—the time in seconds the email was read. Postmark stops recording after 20 seconds.
  • Geo—this JSON object contains geographic information Postmark was able to parse from the IP address the open request came from. This object may only be partially populated in certain cases.

Example JSON webhook data

{
  "FirstOpen": true,
  "Client": {
    "Name": "Chrome 35.0.1916.153",
    "Company": "Google",
    "Family": "Chrome"
  },
  "OS": {
    "Name": "OS X 10.7 Lion",
    "Company": "Apple Computer, Inc.",
    "Family": "OS X 10"
  },
  "Platform": "WebMail",
  "UserAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/35.0.1916.153 Safari\/537.36",
  "ReadSeconds": 5,
  "Geo": {
    "CountryISOCode": "RS",
    "Country": "Serbia",
    "RegionISOCode": "VO",
    "Region": "Autonomna Pokrajina Vojvodina",
    "City": "Novi Sad",
    "Zip": "21000",
    "Coords": "45.2517,19.8369",
    "IP": "188.2.95.4"
  },
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ReceivedAt": "2014-06-01T12:00:00",
  "Tag": "welcome-email",
  "Recipient": "john@example.com"
}

Testing with curl

If you’re developing on your local machine or don’t have a public URL for your API, the curl request to the right has an example webhook POST request. Replace <your-url> with the API route that you want to use for your webhook URL. The curl request will allow you to verify that your webhook URL is able to accept requests with the same JSON format that the Postmark servers will use.

Example curl call

curl <your-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "FirstOpen": true, "Client": { "Name": "Chrome 35.0.1916.153", "Company": "Google", "Family": "Chrome" }, "OS": { "Name": "OS X 10.7 Lion", "Company": "Apple Computer, Inc.", "Family": "OS X 10" }, "Platform": "WebMail", "UserAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/35.0.1916.153 Safari\/537.36", "ReadSeconds": 5, "Geo": { "CountryISOCode": "RS", "Country": "Serbia", "RegionISOCode": "VO", "Region": "Autonomna Pokrajina Vojvodina", "City": "Novi Sad", "Zip": "21000", "Coords": "45.2517,19.8369", "IP": "188.2.95.4" }, "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483", "ReceivedAt": "2014-06-01T12:00:00", "Tag": "welcome-email", "Recipient": "john@example.com" }'

How you can use the data

With the data provided by open tracking, you might able to answer some interesting questions for your business:

  • Which users aren’t looking at their emails?
  • Which subjects result in longer read times?
  • Where are my users reading email?
  • What devices are my users using to view my emails?