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.
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:
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.
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.Metadata—custom metadata that was included in the email.{
"RecordType": "Delivery",
"ServerId": 23,
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Recipient": "john@example.com",
"Tag": "welcome-email",
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
"Details": "Test delivery webhook details"
}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.
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" }'There are many possible uses for the data provided by using the delivery webhook: