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.