Delivery webhook

What is a delivery webhook? #

The Delivery webhook is a way for Postmark to notify your application that an email was successfully delivered to the receiving server. This can be useful in a variety of situations, such as to provide your customers with real-time delivery events, measure how long it takes for an email to get to their inboxes, or simply for auditing purposes.

In Postmark, an email is considered successfully delivered when the destination email server returns an OK response after delivery is attempted. When that happens, Postmark adds a delivery confirmation for that particular email (and that particular recipient, since there can be multiple). At the same time, if the webhook is enabled, a hook is posted to your delivery webhook URL. Please note that at this point the email is out of Postmark's hands, and the receiving server still has to send the email to the user's inbox. This usually happens instantly, but in rare cases, such as when an internal server firewall is set up, emails can get queued by the receiving server.

You could also use the Messages API to pull data about delivery confirmations, but with the delivery webhook Postmark pushes your delivery confirmation as it happens. A delivery webhook will push data to your application in easily parsable JSON format.

Set the delivery webhook URL #

The delivery webhook URL is a server setting. You can only have one delivery webhook URL per server. You can enable the webhook in the following ways:

Using the Postmark website

When logged into Postmark, select the server and go to the “webhooks” tab. Click “Add webhook” and input your webhook URL in the “Webhook URL” field and then select the “delivery” checkbox.

Using the API

You can modify the DeliveryHookUrl field using the Servers API to modify existing servers. You can also use the Servers API to create servers and set the DeliveryHookUrl field at the same time.

Delivery webhook data #

An example of the full JSON document that would be POSTed to your webhook URL is to the right. A brief description of some of the more interesting fields is below:

Recipient—the email address of the recipient.
Tag—delivery tag that was used when the message was sent.
DeliveredAt—timestamp of when email was delivered.
Details—response line received from the destination email server.

Example JSON webhook data

{
  "RecordType": "Delivery",
  "ServerId": 23,
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Recipient": "john@example.com",
  "Tag": "welcome-email",
  "DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
  "Details": "Test delivery webhook details"
}

Testing the delivery 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 '{ "ServerID": 23, "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483", "Recipient": "john@example.com", "Tag": "welcome-email", "DeliveredAt": "2014-08-01T13:28:10.2735393-04:00", "Details": "Test delivery webhook details" }'

How you can use the delivery data #

There are many possible uses for the data provided by using the delivery webhook:

You get instantly informed that a particular email has been delivered and you can initiate further action based on that event.
You could use the data to generate statistics that are specific to your application.
You could use the data to provide your users with an UI enabling them to see what happened with their email notifications.
You could use the data to see how fast your emails are getting delivered.