How to Set Up a Bounce Webhook

 
Curious about what bounce webhooks are and how you can start using them to track bounces? Read on for more information on how bounce webhooks work, how you can set your bounce webhook URL in your Postmark settings, and what some of the potential uses are.

What does a bounce webhook do?

Postmark’s bounce webhooks allow you to receive real-time notifications every time a message you send through Postmark generates a bounce. These bounce notifications are sent as an HTTP POST to a URL you set in your Postmark Server settings. Bounce webhook notifications include information like the sender, recipient, subject, and reason for the bounce.
The HTTP POSTs containing the bounce information are sent as JSON with this format:
{
  "ID": 42,
  "Type": "HardBounce",
  "TypeCode": 1,
  "Name": "Hard bounce",
  "Tag": "Test",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerId": 23,
  "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
  "Details": "Test bounce details",
  "Email": "john@example.com",
  "From": "sender@example.com",
  "BouncedAt": "2014-08-01T13:28:10.2735393-04:00",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": true,
  "Subject": "Test subject",
  "Content": "<Full dump of bounce>",
}

What can I use bounce notifications for?

Bounce webhook events can be used in many ways, such as:
  • Notifying senders of a bounced email
  • Spotting bounce trends
  • Preventing further sending to bad addresses from your application
  • Keeping track of which addresses bounced so the recipients can be contacted through another channel
How you end up using the bounce notifications is up to you. You can develop any additional functionality you need in your bounce webhook URL application code for acting on bounce notifications you receive.

What do I need to receive the bounce notifications?

Before setting your bounce webhook URL in your Postmark Server settings, use our documentation for help with developing the code for receiving the bounce webhook events with. If you are not familiar with receiving HTTP POSTs, you may need the assistance of a developer for developing and hosting the application that receives and processes the bounce notifications. Save some time and get going faster by utilizing our Postmark labs open source webhooks project, that lets you quickly start using all of Postmark’s webhooks.

How do I set my bounce webhook URL in Postmark?

When your URL is hosted and able to receive and process bounce webhook notifications, you are ready to set that URL in your Postmark Server settings.
  1. Open up your Server in Postmark you want to receive bounce webhook notifications for
  2. Click Settings
  3. Click Outbound
  4. Enter in your bounce webhook URL in the Bounce webhook field.

Once your URL is entered, click the Check button to receive a test bounce webhook event at that URL and confirm everything is working. Click Savechanges once you are done testing the URL.

Conclusion

Now you are ready to take advantage of this powerful feature and begin using bounce webhooks to receive bounce notifications today.
If you have any questions, get in touch with us and we can help!
Last updated December 6th, 2017

Still need some help?

Our customer success team is here to help!