How do I enable delivery webhooks?

Instead of having to poll the API or use our UI to check on the delivery status and get delivery details for an email you sent, you can instead receive updates pushed to you in real-time (as JSON) when an email is delivered. By setting up delivery webhooks for your Server(s) in Postmark, you can confirm the delivery details for emails you send without having to log into Postmark or poll our Messages API. You can set your delivery webhook URL(s) using both our API and UI.

Set delivery webhook URL using Postmark UI

Log into Postmark and open the Server you want to configure the delivery webhooks URL for. Go to the server settings page and click the“Add webhook” button. Add your webhook URL in the“Webhook URL” field and then click 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 Credentials 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":"a94dfe84-8ab9-43cf-8a1c-ac234c296e25",
	"Recipient":"recipeint@example.com",
	"Tag":"Your Tag",
	"DeliveredAt":"2016-12-01T15:41:45-05:00",
	"Details":"smtp;250 2.0.0 OK 1480624905 l186si10190883ite.73- gsmtp"
}

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.