Bounce webhook

What is a bounce webhook? #

One of the reasons you send emails through Postmark is to handle all of the possible bounces that email servers can return. However, your application still needs the information about those bounces in an easy to use format. You could use the Bounce API to pull data about your bounces. For some applications, it’s easier to use a webhook for Postmark to push your bounce data as bounces occur. A bounce webhook will push data to your application in an easily parsable, JSON format, as soon as Postmark processes the bounce report.

Bounce webhooks are triggered for bounces that resulted from outgoing email. So, your webhook would receive data for Hard Bounces, Soft Bounces, Undeliverable bounces, etc.

It is also possible to generate fake bounces by using our black hole domain. This allows you to test your bounce webhook in a safe way, as the bounces won't affect your sending domain or reputation. Check out our help article on how to test bounces.

Note: The datetime for the BouncedAt field will be in ISO 8601 format.

The official Postmark Slack App

Side note: an easy way to get bounce notifications is through our official Slack App. Search for "Postmark Bot" in the Slack App Directory, or install directly from the Slack app page.

Use Rebound to prompt your users to update their email address

If you use Postmark and you're not at a point where you can custom build full bounce handling functionality into your application, you can use Rebound to quickly add in basic bounce handling functionality using JavaScript. Rebound prompts your customers to update their email address if an email you sent them hard bounced.

Use Zapier to notify your senders with an email if a message they sent bounced

For a low effort method of using bounce webhooks to alert your senders of bounces, check out our help article on using Zapier to automatically alert your senders of bounces.

Set the bounce webhook URL #

Using the Postmark website

When logged into Postmark, select the Server, the Message Stream, and then go to the Webhooks tab. Choose Add webhook and input your webhook URL in Webhook URL and then select the Bounce checkbox.

Using the API

You can modify the Bounce field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the Bounce field at the same time.

Bounce webhook data #

An example of the full JSON document that would be POSTed to your webhook URL is to the right. A brief description of some of the more interesting fields is below:

ID—you can use the ID to make different requests to the Bounce API. This is an int64 value.
Type—the classification that Postmark assigned the bounce. All of the bounce types are listed on the Bounce API reference page. Note that that spam complaints, unsubscribes/subscribes, or manual deactivations have their own webhooks and are not trigged via the Bounce webhook.
Metadata—custom metadata that was included in the email.
Email—the email address that bounced.
From—the original sender of the bounced email.
BouncedAt—timestamp of when bounce occurred.
Inactive—lets you know if this bounce caused the email address to be deactivated.
CanActivate—lets you know if this address can be activated again.
Content(optional)—The full content of the email bounce. This is off by default but can be enabled.

Example JSON webhook data

{
  "RecordType": "Bounce",
  "MessageStream": "outbound",
  "ID": 4323372036854775807,
  "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>"
}

Testing the bounce webhook with curl #

If you’re developing on your local machine or don’t have a public URL for your API, the curl request to the right has an example webhook POST request. Replace <your-url> with the API route that you want to use for your webhook URL. The curl request will allow you to verify that your webhook URL is able to accept requests with the same JSON format that the Postmark servers will use.

Example curl call

curl <your-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "ID": 4323372036854775807,
  "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,
  "RecordType": "Bounce",
  "Subject": "Test subject"
}'

How you can use the bounce data #

There are many possible uses for the data provided by using the bounce webhook:

You could instantly help users correct their email if their sign up email address bounces.
You could use the data to generate statistics that are specific to your application.
You could use the data to reactivate email addresses due to hard bounces using the activate bounces API.
You could use the data to alert your team when certain emails bounce.

Rebound JavaScript Snippet #

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.