Implementing a bounce hook in ASP.NET

Bounce hooks are a mechanism to receive an almost real time notification when an email that you have sent bounces back because of some reason. As described in the developer documentation, Postmark can issue a HTTP POST request to a web page you control and submit the bounce data whenever it parses an incoming bounce.

The problem

ASP.NET, and especially WebForms is targeted at mostly accepting posted forms and extracting data from form controls and detecting other input events. Postmark will issue a HTTP POST that will not contain the usual parameters and a __VIEWSTATE form field. The request body will contain a JSON string with the bounce data that you have to extract and parse yourself.

Extracting the JSON request body

To do that, you need to use the lower-level HttpRequest object and read the request input stream. The easiest way is to construct a StreamReader object and call its ReadToEnd() method:

var requestReader = new StreamReader(Request.InputStream);  
var requestJson = requestReader.ReadToEnd();

Using Json.NET to parse incoming bounces

Json.NET can easily deserialize a JSON object into a .NET one, but you will have to define a Bounce object yourself with all the respective properties:

public class Bounce {
  public int ID { get; set; }
  public string Type { get; set; }
  public string Email { get; set; }
  public string From { get; set; }
  public DateTime BouncedAt { get; set; }
  public string Details { get; set; }
  public bool DumpAvailable { get; set; }
  public bool Inactive { get; set; }
  public bool CanActivate { get; set; }
}

Once you have the Bounce class defined, you can call JsonConvert.DeserializeObject() on the JSON string:

var bounce = JsonConvert.DeserializeObject<Bounce>(requestJson);

Testing Bounces

Want to test your integration with the Postmark Bounces API or Bounces webhook? 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.