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 generates a bounce. These bounce notifications are sent as an HTTP POST to a URL you set in your Postmark 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>"
}

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 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 Message Stream’s settings.

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

Process of adding a webhook

Testing bounces in Postmark

Postmark offers a black hole domain that allows you to test all possible bounce responses and each of these will trigger the bounce webhook. Emails sent to that domain do not affect your sending reputation.

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 Message Stream sending today.

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