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’s Transactional Message Stream 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 a Transactional Message Stream generates a bounce. These bounce notifications are sent as an HTTP POST to a URL you set in your Postmark Transactional Message Stream’s 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:

{
 "RecordType": "Bounce",
 "MessageStream": "transactional",
 "ID": 42,
 "Type": "HardBounce",
 "TypeCode": 1,
 "Name": "Hard bounce",
 "Tag": "Test",
 "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
 "Metadata" : {
 "a_key" : "a_value",
 "b_key": "b_value"
 },
 "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": "2019-11-05T16:33:54.9070259Z",
 "DumpAvailable": true,
 "Inactive": true,
 "CanActivate": true,
 "Subject": "Test subject",
 "Content": "<Full dump of bounce>"
}

Will the Bounce Webhook work with my Broadcast Message Streams?

No. The Bounce Webhook is only available for messages sent through a Transactional Message Stream. Broadcast Message Streams will not be able to use use the Bounce Webhook, though you can use the similar Subscription Change Webhook to get notifications when a recipient becomes inactive due to a hard 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 Transactional Message Stream’s 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 a Postmark Transactional Message Stream’s settings.

  1. Select your Server and then click on the Transactional Message Stream you want to receive bounce webhook notifications for
  2. Click Webhooks and then the Add webhook button
  3. Enter in your bounce webhook URL in the Webhook URL field
  4. Once your URL is entered, click the bounce checkbox and then test your webhook URL to confirm everything is working.
  5. Save your changes once you are done testing the URL.

Process of adding a webhook

Rebound

The Rebound JavaScript snippet (once installed on your website) will tap into the Postmark API to check for hard bounces and prompt your customers to update their email address if they’ve experienced deliverability issues in the past.

Screenshot of rebound JavaScript snippet

Conclusion

Now you are ready to take advantage of this powerful feature and begin using bounce webhooks to receive bounce notifications for your Transactional Message Stream sending today.

If you have any questions, get in touch with us and we can help!

Last updated June 11th, 2020

Still need some help?

Our customer success team has your back!