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.
Note: The datetime for the DeliveredAt field will be in ISO 8601 format.
When logged into Postmark, select the Server, the Message Stream, and the go to the Webhooks tab. Choose Add webhook and input your webhook URL in Webhook URL and then select the Delivery checkbox.
You can modify the Delivery field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the Delivery 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.{
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Recipient": "john@example.com",
"DeliveredAt": "2019-11-05T16:33:54.9070259Z",
"Details": "Test delivery webhook details",
"Tag": "welcome-email",
"ServerID": 23,
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"RecordType": "Delivery",
"MessageStream":"outbound"
}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 '{
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Recipient": "john@example.com",
"DeliveredAt": "2014-08-01T13:28:10.2735393-04:00",
"Details": "Test delivery webhook details",
"Tag": "welcome-email",
"ServerID": 23,
"Metadata": {
"a_key": "a_value",
"b_key": "b_value"
},
"RecordType": "Delivery",
"MessageStream": "outbound"
}'There are many possible uses for the data provided by using the delivery webhook: