-
Notifications
You must be signed in to change notification settings - Fork 45
Version 2.0 Upgrade Guide
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.
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.
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...
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).
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 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 "Async-first", meaning that they return Task
s instead of response objects directly. You can use them with the async/await keywords, which are generally cleaner, compared to the older IAsyncResult
paradigm:
var client = new PostmarkClient("<server token>");
try{
var asyncResult = client.BeginSendMessage(
"sender@example.com", "recipient@example.com",
"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.
}
var client = new PostmarkClient("<server token>");
try{
var result = await client.SendMessageAsync(
"sender@example.com", "recipient@example.com",
"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(
"sender@example.com", "recipient@example.com",
"A Test Message", "<b>Hello!")
.WaitForResult();
if(result.Status == PostmarkStatus.Success){ /*...*/ }
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);
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.
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
:
client.SendMessage(
new PostmarkMessage(
new MailMessage("sender@example.com", "recipient@example.com"){
Subject = "A Test Message",
Body = "<b>Hello!</b>"
})
);
var result = await client.SendMessageAsync(
new MailMessage("sender@example.com", "recipient@example.com"){
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.
The Postmark.Net client can be installed from NuGet.
For additional information about the capabilities of the Postmark API, see http://developer.postmarkapp.com/.
- Getting Started
- Version 2.0 Upgrade Guide
- Sending Email
- Searching Sent Messages
- Analyzing Sent Messages
- Processing Inbound Email
- Retrieving Message Statistics
- Handling Bounces
- Managing Suppressions
- Working with Message Streams
- Managing Your Account
- Troubleshooting Async&Await
- Version 1.x Overview
- Sending Email
- Sending Batch Emails
- Sending Attachments
- Sending Inline Images
- Using
MailMessage
- Using the Bounce API
- [Getting Send Statistics](Sending Statistics)
- Adding Custom Email Headers