User guide

API reference


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 it happens. A bounce webhook will push data to your application in easily parsable JSON format as soon as Postmark processes the bounce report.

Bounce webhooks are triggered for bounces and spam complaints that resulted from outgoing email. So, your webhook would receive data for Hard Bounces, Soft Bounces, Spam Complaints, etc.

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 Github page.  

Set the bounce webhook URL #

The bounce webhook URL is a server setting. You can only have one bounce webhook URL per server.

Using the Postmark website

When logged into Postmark, select the server and go to the “Settings” tab and then the ”Outbound“ tab. The “Bounce Webhook” field is where you should input your webhook URL.

Using the API

You can modify the BounceHookUrl field using the Servers API to modify existing servers. You can also use the Servers API to create servers and set the BounceHookUrl 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.
  • Type—the classification that Postmark assigned the bounce. All of the bounce types are listed on the Bounce API reference page.
  • Email—the email address that bounced.
  • From—the original sender of the bounced email.
  • 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. Email addresses that are deactivated due to spam complaints cannot be reactivated.
  • Content(optional)—The full content of the email bounce. This is off by default but can be enabled.

Example JSON webhook data

  "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>",

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": 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" }'

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.