My Brain on Code

Postmark Bounce Hooks With ASP.NET MVC 3

At my work, we use Postmark for email delivery. They provide a nice way to receive notifications that a particular email bounced. This is called a bounce-hook. A bounce-hook allows you to specify a URL that Postmark will make a POST request to when an email bounces.

We use the ASP.NET MVC framework version 3 at my work. I was tasked with setting up a way to receive Postmark’s bounce hooks for our system. Luckily it’s pretty easy to do.

I created a class that represents the JSON Postmark sends along with a bounce- hook:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
[Serializable]
public class PostmarkBounceHookJson
{

    public DateTime BouncedAt { get; set; }

    public bool CanActivate { get; set; }

    [AllowUnsafeHtml]
    public string Description { get; set; }

    [AllowUnsafeHtml]
    public string Details { get; set; }

    public bool DumpAvailable { get; set; }

    [AllowUnsafeHtml]
    public string Email { get; set; }

    public int ID { get; set; }

   public bool Inactive { get; set; }

    public Guid MessageID { get; set; }

    [AllowUnsafeHtml]
    public string Name { get; set; }

    [AllowUnsafeHtml]
    public string Subject { get; set; }

    [AllowUnsafeHtml]
    public string Tag { get; set; }

    public BounceType Type { get; set; }

    public int TypeCode { get; set; }
}

// The bounce types postmark supports
public enum BounceType
{
    HardBounce,

    Transient,

    Unsubscribe,

    Subscribe,

    AutoResponder,

    AddressChange,

    DnsError,

    SpamNotification,

    OpenRelayTest,

    Unknown,

    SoftBounce,

    VirusNotification,

    ChallengeVerification,

    BadEmailAddress,

    SpamComplaint,

    ManuallyDeactivated,

    Unconfirmed,

    Blocked,
}

The reason for all the AllowUnsafeHtml attributes is because Postmark sends the raw details which can contain some data that ASP.NET with throw a fit about (i.e. it throws exceptions). So we use the AllowUnsafeHtml to get around that. Just be sure you aren’t directly displaying it to a user and that you sanitize it yourself.

Then, I created a controller to receive the bounce-hook POST:

1
2
3
4
5
6
7
8
9
10
11
12
13
public class PostmarkController : Controller
{

    [HttpPost]
    public EmptyResult BounceHook(PostmarkBounceHookJson json)
    {
        // do your own custom logic with the bounce here...

        // return an emtpy result which is basically just a HTTP 200 OK
        return new EmptyResult();
    }

}

The nice thing about MVC 3 is that it will automatically model bind the POSTed JSON to our PostmarkBounceHookJson class.

Now the only thing left to do is log in to your Postmark account and go into your server settings and set up the correct bounce hook URL.

It’s worth pointing out that you only get one bounce per email until you re- activate that email. For example, say you send an email to john@someinvalidemail.com. Obviously it’s an invalid email address so you’ll get a bounce POSTed to you. Now if you try to send an email to that same email again, you won’t get another bounce POSTed to you. The idea of a bounce hook is that when you get one for a specific email, you’ll correct the email and try again with the new one. However, there is a way to re-activate an email if you suspect it was just a fluke. See here for how to do that.