How do I enable delivery webhooks?
Instead of polling the Postmark API or using our UI to check on the delivery status, Postmark offers a devlivery webhook. This webhook pushes updates in real-time (as JSON) when a message gets delivered. You can set your delivery webhook URL(s) using both our API and UI.
Set delivery webhook URL using Postmark UI
When logged into Postmark, select the server, then stream 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. Before saving your changes, be sure to test your webhook to confirm that it works.
Set delivery webhook URL when creating a new Server using the API
Use the following JSON and API endpoint for creating a new Server that sets the delivery webhook URL when the Server is created:
Endpoint:
https://api.postmarkapp.com/servers
HTTP Method: POST
Headers:
- Accept: application/json
- Content-Type: application/json
- X-Postmark-Account-Token: YourAccountAPIToken
You can retrieve your Account API Token from the
Account tab in your Postmark Account.
Body:
{
"Name":"Delivery Webhook Test Server",
"Color":"blue",
"SmtpApiActivated": true,
"RawEmailEnabled": false,
"InboundHookUrl": null,
"BounceHookUrl": null,
"OpenHookUrl": null,
"PostFirstOpenOnly": false,
"TrackOpens": false,
"InboundDomain": null,
"InboundSpamThreshold": 5,
"DeliveryHookUrl":"http://yourdomain.com/webhooks/delivery"
}
Set delivery webhook URL for an existing Server using the API
If you want to set a delivery webhook URL for an existing Server, you can do that with the following example JSON and endpoint:
Endpoint:
https://api.postmarkapp.com/server
HTTP Method: PUT
Headers:
- Accept: application/json
- Content-Type: application/json
- X-Postmark-Server-Token: YourServerAPIToken
You can retrieve the Server API Token from the API Tokens tab of your Postmark Server you want to set the delivery webhook URL for.
Body:
{
"DeliveryHookUrl":"http://yourdomain.com/webhooks/delivery"
}
Example delivery webhook event
When you receive a delivery webhook event at your URL it will have the following format:
{
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Recipient": "john@example.com",
"DeliveredAt": "2019-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"
}
MessageID: The message ID associated with the email.
Recipient: Email address of recipient who received the email.
Tag: If you placed a tag on the email when you sent it, the tag will also show up in the JSON you receive with the delivery details.
DeliveredAt: Timestamp of when the email was acknowledged as delivered by the receiving mail server.
Details: Full response details we received from the receiving mail server.
Integrate
Now that you know how to configure your delivery webhook settings, you can start using the delivery information in your application to keep your users updated in real-time on the delivery status of emails they send.
For more information, see our
developer documentation for delivery webhooks.