PostalApiClient 1.1.0

PostalApiClient

.NET Core API client for postal mail delivery platform

Available on NuGet

Usage

1. Register PostalClient in startup\builder

// Read configuration from default section "PostalClient"
builder.Services
    .AddPostalApiClient(builder.Configuration);

// or set options from action
builder.Services
    .AddPostalApiClient(opt =>
    {
        opt.Server = "http://mypostal.domain";
        opt.ApiKey = "Api-Credential-Key";
    });

// or read options from custom configuration section
builder.Services
    .AddPostalApiClient(builder.Configuration.GetSection("MyCustomSection"));

// or use combination from custom configuration section
// and action for override some options
builder.Services
    .AddPostalApiClient(builder.Configuration.GetSection("MyCustomSection"),
        options => { 
            options.ApiKey = "OtherApiKey"; 
        });

// Can use built-in extension methods for setting HttpClient
// e.g. add request handler or logger or retry policy and etc.
builder.Services
    .AddPostalApiClient(builder.Configuration)
    .AddLogger<CustomHttpLogger>()
    .AddHttpMessageHandler<MyRequestHandler>();

2. Get client from DI

// e.g. in controller
public class PostalController : ControllerBase
{
    private readonly PostalClient _postalClient;
    public PostalController(PostalClient client)
    {
        _postalClient = client;
    }
    
    // ... actions
}

3. Call API methods

var (result, error) = await _postalClient.GetMessageDeliveriesAsync(messageId); 

if (error != null)
{
    // error handler
}
// continue code with success result

All methods return tuples with two nullable items: Result and Error. Always check Error for make sure the operation is successful.

Samples

// Send message
var message = new PostalMessage()
{
    To = new List<string>
    {
        "example@example.com",
    },
    From = "admin@localhost.com",
    Subject = "Subject",
    PlainBody = "Message body text",
    Sender = "Sender email/name",
    Tag = "Custom message tag",
    ReplyTo = "replyTo@example.com",
    Attachments = new List<PostalMessageAttachment>
    {
        new PostalMessageAttachment()
        {
            Data = "ContentBse64string",
            Name = "Attachment №1",
            ContentType = "image/jpeg"
        }
    },
    Headers = new Dictionary<string, string>
    {
        {"CustomMessageHeader","HeaderValue"}
    }
};

var (result, error) = await _postalClient.SendMessageAsync(message); 

// Get message details
await _postalClient.GetMessageDetailsAsync(messageId, MessageExpansion.Status | MessageExpansion.PlainBody);

All available methods and description see in official docs or samples in Demo project

4. Webhooks

Simple usage

Create webhook in postal server and add POSTmethod in controller

[HttpPost]
public IActionResult ReceiveWebhook([FromBody] PostalWebhook payload)
{
    // ... 
    // Your webhook handler code
    
    return Ok();
}

PostalWebhook support payload for all events

Signature verification

You're can verification request signature for approval that request was sent by your postal server.

For this need get public key from server DKIM record and set option DkimP

# run on postal server machine 
# and copy the p=... part of the TXT record (without the semicolon at the end)
postal default-dkim-record

// Add public key to ApiClient option or in appsettings.json
builder.Services
    .AddPostalApiClient(opt =>
    {
        opt.DkimP = "p= part from drim TXT record";
    });

After can use service PostalWebhookVerifier for validate model PostalWebhook signature

[HttpPost]
public async Task<IActionResult> ReceiveWebhook([FromBody] PostalWebhook payload, 
    [FromServices] PostalWebhookVerifier signatureVerifier)
{
    // Check signature
    var isVerified = signatureVerifier.IsSignatureVerified(payload, Request.Headers);
    
    // !!IMPORTANT!! not use this method after request body already read.
    // This Request.Body usually is empty and verifier return always false
    var badUse = await signatureVerifier.IsSignatureVerifiedAsync(Request);
     
    // Your webhook handler code
    /// ...
    
    return Ok();
}

You're can install package PostalApiClient.Mvc.Extensions with mvc dependencies and use attribute for request signature automatic validation

[HttpPost]
[PostalSignatureVerify]
public IActionResult ReceiveWebhookWithSignatureVerify([FromBody] PostalWebhook payload)
{
    // ... 
    // Your webhook handler code

    return Ok();
}

or write custom middleware for verification with use extension method

// some code before verification

var isVerified = await context.HttpContext.CheckPostalSignatureAsync();

// some code after verification