How do I automatically alert senders when an email bounces?

When you use Postmark for outbound sending, all bounce feedback is sent to our return-path so that we can display it in your Activity pages for you, as well as have the information available via our API and webhooks. The tradeoff for Postmark receiving bounce feedback for emails you send is that the bounce details are not sent to the email address used in the From header for emails that bounce. 

This help article will show you how to use bounce webhook events to send emails to the original sender with the bounce information.

Requirements

Before you can start automatically alerting senders when a bounce occurs you must have already set your bounce webhook URL in your Postmark Server and have your URL successfully receiving bounce webhook notifications we send. If you have not completed this step, return to this help article after you have your bounce webhook URL configured and working properly. Documentation on our bounce webhook can be found here.

Get the From address

When you receive a bounce webhook notification to your URL it will have this JSON schema:
{
  "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"
}
We are specifically interested at this point in the “From” field in the JSON we receive when a bounce occurs. This tells us who sent the email that ended up bouncing and needs to be notified. After parsing the From email address and storing it, the next step is alerting this sender that the bounce occurred and provide the appropriate details.

Alerting the Sender

Since you are already sending with Postmark you should be familiar with how to construct and send emails using our API or SMTP. What you choose to populate the bounce alert emails to senders with is up to you, but we recommend including at a minimum the recipient’s email address, email subject, and the why the email bounced. 
In the bounce webhook JSON you will want to parse and store the following fields for later use in the email alert you send to the original sender:
  • Email - recipient’s email address that caused the bounce
  • From - sender’s email address(where we will send the bounce alert)
  • Details - details of the bounce
  • Description - description of the bounce
  • Subject - the subject line of the email that bounced
You can optionally include the bounced email’s content so the sender clearly understands which email they sent to the recipient bounced, though that will involve an additional API call to our Messages API to get the HtmlBody and TextBody fields for the MessageID that bounced.
Using these fields from the bounce webhook notification you can then construct the email to send to the original sender letting them know that an email they sent bounced.
Last updated January 4th, 2017

Still need some help?

Our customer success team is here to help!