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.

Note: The datetime for the ReceivedAt field will be in ISO 8601 format.

Set the open webhook URL #

Using the Postmark website

When logged into Postmark, select the Server, the Message Stream, and then go to the Webhooks tab. Choose Add webhook and input your webhook URL in Webhook URL and then select the Open checkbox.

Using the API

You can modify the Open field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the Open field at the same time.

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.
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.
Metadata—custom metadata that was included in the email.
ReceivedAt—the timestamp of when a message was opened.

Example JSON webhook data

{
  "RecordType": "Open",
  "MessageStream": "outbound",
  "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",
  "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",
  "Metadata" : {
    "a_key" : "a_value",
    "b_key": "b_value"
   },
  "ReceivedAt": "2019-11-05T16:33:54.9070259Z",
  "Tag": "welcome-email",
  "Recipient": "john@example.com"
}

Testing the open webhook 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",
  "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": "2019-05-21T18:24:47Z",
  "Tag": "welcome-email",
  "Recipient": "john@example.com",
  "RecordType": "Open"
}'

How you can use the open tracking 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?
Where are my users reading email?
What devices are my users using to view my emails?