PostKit 10.0.1

PostKit

A MimeKit infused implementation of the Postmark API.

Quickstart

Prerequisites

• .NET 8.0 or later
• A Postmark account with a Server API Token
• Verified sender email addresses in your Postmark account

Installation

Install PostKit via NuGet:

dotnet add package PostKit

Configuration

Add PostKit to your services and configure your Postmark API token:

// Program.cs (Minimal API / Web App)
using PostKit;

var builder = WebApplication.CreateBuilder(args);

// Add PostKit to services
builder.Services.AddPostKit();

var app = builder.Build();

Configure your Postmark Server API Token in appsettings.json:

{
  "PostKit": {
    "ServerApiToken": "your-postmark-server-token-here"
  }
}

Or set it via environment variables:

PostKit__ServerApiToken=your-postmark-server-token-here

If you need multiple Postmark configurations (for example, separate servers or tenants), register keyed services with AddKeyedPostKit. Each keyed registration binds to PostKit:{configurationKey}; if you omit configurationKey, the serviceKey.ToString() value is used.

builder.Services.AddKeyedPostKit("Marketing"); // binds PostKit:Marketing

public enum PostmarkServer
{
    Development,
    Production
}

builder.Services.AddKeyedPostKit(PostmarkServer.Development); // binds PostKit:Development
builder.Services.AddKeyedPostKit(PostmarkServer.Production, "Default"); // binds PostKit:Default

{
  "PostKit": {
    "Marketing": { "ServerApiToken": "token-1" },
    "Development": { "ServerApiToken": "token-2" },
    "Default": { "ServerApiToken": "token-3" }
  }
}

Basic Usage

PostKit uses a fluent builder pattern with the following capabilities:

• Email Addresses: Support for simple strings, name/address pairs, or MimeKit MailboxAddress objects
• Multiple Recipients: Chain AlsoTo(), AlsoCc(), or AlsoBcc() to add additional recipients
• Validation: Automatic validation of email addresses, character limits, and required fields

Simple Email

using PostKit;

// Inject IPostKitClient via dependency injection
public class EmailService
{
    private readonly IPostKitClient _postKitClient;

    public EmailService(IPostKitClient postKitClient)
    {
        _postKitClient = postKitClient;
    }

    public async Task SendWelcomeEmailAsync()
    {
        var email = Email.CreateBuilder()
            .From("noreply@yourapp.com")
            .To("user@example.com")
            .WithSubject("Welcome to Our Service!")
            .WithTextBody("Thank you for signing up!")
            .Build();

        await _postKitClient.SendEmailAsync(email);
    }
}

Rich HTML Email

var email = Email.CreateBuilder()
    .From("Sarah Johnson", "sarah@company.com")
    .To("customer@example.com")
    .WithSubject("Your Order Confirmation")
    .WithHtmlBody(@"
        <h1>Order Confirmed!</h1>
        <p>Thank you for your purchase. Your order #12345 has been confirmed.</p>
        <a href='https://yourapp.com/orders/12345'>View Order Details</a>
    ")
    .WithTextBody("Order Confirmed! Thank you for your purchase. Your order #12345 has been confirmed. View details at: https://yourapp.com/orders/12345")
    .Build();

await _postKitClient.SendEmailAsync(email);

Multiple Recipients

var email = Email.CreateBuilder()
    .From("notifications@company.com")
    .To(new[] { "user1@example.com", "user2@example.com" })
    .Cc("manager@company.com")
    .Bcc("admin@company.com")
    .WithSubject("Team Update")
    .WithTextBody("Important team announcement...")
    .Build();

await _postKitClient.SendEmailAsync(email);

Batch Sending

var welcomeEmail = Email.CreateBuilder()
    .From("noreply@yourapp.com")
    .To("user1@example.com")
    .WithSubject("Welcome!")
    .WithTextBody("Thanks for signing up")
    .Build();

var reminderEmail = Email.CreateBuilder()
    .From("noreply@yourapp.com")
    .To("user2@example.com")
    .WithSubject("Complete Your Profile")
    .WithTextBody("Finish setting up your account")
    .Build();

var batchResult = await _postKitClient.SendEmailBatchAsync(new[] { welcomeEmail, reminderEmail });

if (!batchResult.IsSuccessful)
{
    foreach (var result in batchResult.Results.Where(result => !result.IsSuccessful))
    {
        // Inspect result.Email and result.Message to handle the failure.
    }
}

Advanced Features

var email = Email.CreateBuilder()
    .From("newsletter@company.com")
    .To("subscriber@example.com")
    .ReplyTo("support@company.com")
    .WithSubject("Monthly Newsletter")
    .WithHtmlBody("<h1>Newsletter</h1><p>Check out our latest updates!</p>")
    .WithTag("newsletter")
    .WithMetadata("campaign", "monthly-2024")
    .WithMetadata("segment", "premium-users")
    .WithOpenTracking(true)
    .WithLinkTracking(LinkTracking.HtmlAndText)
    .UsingMessageStream(MessageStream.Broadcast)
    .WithHeader("X-Campaign-ID", "CAMP-001")
    .Build();

await _postKitClient.SendEmailAsync(email);

Attachments and Inline Images

var invoice = Attachment.Create(
    name: "invoice.pdf",
    contentType: "application/pdf",
    content: await File.ReadAllBytesAsync("invoice.pdf"));

var logo = Attachment.Create(
    name: "logo.png",
    contentType: "image/png",
    content: await File.ReadAllBytesAsync("logo.png"),
    contentId: "logo@yourapp.com");

var email = Email.CreateBuilder()
    .From("billing@company.com")
    .To("customer@example.com")
    .WithSubject("Your Monthly Invoice")
    .WithHtmlBody($"<p>Please find your invoice attached.</p><img src=\"{logo.ContentId}\" alt=\"Company Logo\" />")
    .WithAttachment(invoice)
    .WithAttachment(logo)
    .Build();

await _postKitClient.SendEmailAsync(email);

Size Limits

Postmark limits TextBody and HtmlBody to 5 MB each, and total message size (including attachments) to 10 MB. When batching, Postmark accepts up to 500 emails per batch and batch payloads are limited to 50 MB. PostKit uses a conservative estimate to prevent grossly oversized requests. Actual size limits will be enforced by the Postmark API.

Error Handling

PostKit uses LightResults for error handling. SendEmailAsync returns a Result<SendEmailResponse> that contains either the response or error information:

var result = await _postKitClient.SendEmailAsync(email);

if (result.IsSuccess(out var response, out var error))
{
    // Email sent successfully
    Console.WriteLine($"Email sent with MessageId: {response.MessageId}");
}
else
{
    // Handle the error
    Console.WriteLine($"Failed to send email: {error.Message}");
}

Error Types

PostKit may return different types of errors depending on the failure scenario:

HttpError - Returned for HTTP-level failures (network issues, timeouts, non-422 status codes):

if (error is HttpError httpError)
{
    Console.WriteLine($"HTTP error: {httpError.StatusCode} - {httpError.Message}");
}

PostmarkError - Returned for Postmark API validation errors (422 status code):

if (error is PostmarkError postmarkError)
{
    Console.WriteLine($"Postmark error: {postmarkError.ErrorCode} - {postmarkError.Message}");

    // Handle specific error codes
    switch (postmarkError.ErrorCode)
    {
        case PostmarkErrorCode.SenderSignatureNotFound:
            // The From address doesn't have a verified sender signature
            break;
        case PostmarkErrorCode.InvalidEmailRequest:
            // The email request validation failed
            break;
        case PostmarkErrorCode.NotAllowedToSend:
            // Account has run out of credits
            break;
    }
}

See PostmarkErrorCode enum for the complete list of possible Postmark error codes.

Message Streams

Postmark supports different message streams for different types of emails:

// For transactional emails (default)
.UsingMessageStream(MessageStream.Transactional)

// For broadcast/marketing emails
.UsingMessageStream(MessageStream.Broadcast)

// Or use a custom stream ID
.UsingMessageStream("custom-stream-id")

Complete Console Application Example

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using PostKit;

var builder = Host.CreateApplicationBuilder(args);

// Add PostKit
builder.Services.AddPostKit();

var host = builder.Build();

// Get the PostKit client
var postKitClient = host.Services.GetRequiredService<IPostKitClient>();

// Create and send an email
var email = Email.CreateBuilder()
    .From("test@yourapp.com")
    .To("recipient@example.com")
    .WithSubject("Test Email from PostKit")
    .WithTextBody("Hello from PostKit! This email was sent using the PostKit library.")
    .WithHtmlBody("<h1>Hello from PostKit!</h1><p>This email was sent using the <strong>PostKit</strong> library.</p>")
    .Build();

await postKitClient.SendEmailAsync(email);

Console.WriteLine("Email sent successfully!");

Development

The following tables track development progress and map the different Postmark API endpoints to their respective methods in PostKit.

Email API

Bulk Email

Bounce API

Templates API

Server API

Servers API

Message Streams API

Messages API

Domains API

Sender signatures API

Stats API

Triggers: Inbound rules

Webhooks API

Suppressions API

Data Removal API