Version 2.0 Upgrade Guide

Does 2.0 Require Changes to Your App?

If your application targets older versions of .net (v2.0-v4.0), no modifications should be needed. The Postmark.Net NuGet package contains only minor revisions for the assemblies that target these older frameworks; You can continue to use the client as you have in the past.

If your application targets .net 4.5 or higher, you may need to make a few modifications to your code to work with the 2.0 client. We've included some convenience extensions to make this transition easier, which will be discussed in more detail below.

About 2.0:

Version 2.0 of Postmark.Net has been designed from the ground up to take advantage of the latest .net features. This page outlines the major improvements to the library, with information about how and when you need to convert your existing code to leverage these improvements.

---

Super-fast, TL;DR, Upgrade Path:

Add these two lines to your code:

using PostmarkDotNet;
using PostmarkDotNet.Legacy;

In most cases, adding the above two lines to the top of files that use the PostmarkClient should allow you to continue using the client as you did before, without additional modifications.

Of course, we did a lot of work to modernize and improve the library that we think you'll benefit from, so read on for more information...

"Legacy" Extension Methods Ease the Upgrade:

If you have already made extensive use of the PostmarkClient from version 1.x, you can include the "PostmarkDotNet.Legacy" namespace in your code to ease the transition to 2.0. By including this namespace, we simulate most of the 1.x API so that you can minimize code changes when upgrading:

using PostmarkDotNet.Legacy;

These extension methods are supplied to ease the transition to 2.0, but we recommend using the Task-based methods (those methods ending with "Async"), as the syntax and interactions are much simpler, and there is less overhead if you call them directly (instead of proxying them through the legacy extension methods).

The HeaderCollection class replaces the NameValueCollection:

We designed the 2.0 client as a Portable Class Library. However, the NameValueCollection that was used to carry headers in the PostmarkMessage.Headers property is not availble on all platforms. We've replaced this class with a new class called HeaderCollection. If you're working with a legacy codebase, you can use the AsHeaderCollection() extension method to ease the transition:

NameValueCollection headers = ....;

var message = new PostmarkMessage(){
    Headers = headers.AsHeaderCollection(),
    ...
}

The PostmarkBounce class now uses an Integer ID:

The PostmarkBounce class now uses int instead of string for their ID. This was an oversight in the 1.x releases and is being corrected for better type safety in 2.0. you can use int.Parse(stringValue) and intValue.ToString() to convert between these types.

The PostmarkClient is now Task-based:

The PostmarkClient is "Async-first", meaning that they return Tasks instead of response objects directly. You can use them with the async/await keywords, which are generally cleaner, compared to the older IAsyncResult paradigm:

Async Example (v1.x):

var client = new PostmarkClient("<server token>");

try{
    var asyncResult = client.BeginSendMessage(
                             "[email protected]", "[email protected]", 
                             "Test Sending.", "<b>Hello!</b>");

    // This is not ideal IAsyncResult handling, 
    // but used here to simplify example.
    while (!asyncResult.IsCompleted){ Thread.Sleep(50);}

    var result = client.EndSendMessage(asyncResult);
    if (result.Status == PostmarkStatus.Success){ /* Handle success */ }
    else { /* Resolve issue.*/ }

}catch{
    // Exceptions can occur if request times out.
}

Async Example (v2.0):

var client = new PostmarkClient("<server token>");

try{
    var result = await client.SendMessageAsync(
                 "[email protected]", "[email protected]", 
                 "Test Sending.", "<b>Hello!<b/>"

    if (result.Status == PostmarkStatus.Success){ /* Handle success */ }
    else { /* Resolve issue.*/ }
}catch{
    // Exceptions can occur if request times out.
}

While we recommend leveraging the asynchronous capabilities of the 2.0 client, if you want to use any of the client calls synchronously, we've included an extension method to do so:

var sendResult = client.SendMessageAsync(
                        "[email protected]", "[email protected]", 
                        "A Test Message", "<b>Hello!")
                        .WaitForResult();
if(result.Status == PostmarkStatus.Success){ /*...*/ }

The PostmarkClient Eliminates Redundant Members:

The PostmarkClient class no longer implements Authority or ServerToken properties. Both of these properties can be specified on the PostmarkClient constructor. Instead of "reusing" clients with new tokens/authorities, instantiate new client objects with the values you want to use.

Due to the fact that .net 4.5 allows "optional" parameters, the client class also eliminates a large number of method overloads that allowed for many permutations of methods with a different number of parameters. Now, you may call a client method using only the parameters you need, omitting any that are not applicable:

var softBounces = await client
    .GetBouncesAsync(type: PostmarkBounceType.SoftBounce);

Some Functionality is Supplied as Extension Methods:

In order to keep the core client class simple and easy to test, some functionality is supplied using "extension methods." Therefore, whenever you use PostmarkClient, you should include this using statement at the top of your file:

using PostmarkDotNet;

namespace YourApplication{
    class AClass{
        //....
    }
}

This will ensure that all functionality is exposed to through the Visual Studio's Code Completion.

Method of Sending MailMessage is Improved:

In the 1.x client, it was necessary to construct a PostmarkMessage from a MailMessage before sending with the client. In 2.0, you can send a MailMessage directly, without first creating a PostmarkMessage:

Send a MailMessage (v1.0):

client.SendMessage(
    new PostmarkMessage(
        new MailMessage("[email protected]", "[email protected]"){
            Subject = "A Test Message",
            Body = "<b>Hello!</b>"
        })
);

Send a MailMessage (v2.0):

 var result = await client.SendMessageAsync(
        new MailMessage("[email protected]", "[email protected]"){
            Subject = "A Test Message",
            Body = "<b>Hello!</b>"
        });

Note that some .net profiles do not support MailMessage, and as a result, you will need to use PostmarkMessage on those profiles.