Posta .NET SDK

The .NET SDK for Posta, the self-hosted email delivery and inbound platform.

Installation

dotnet add package Posta

Quick start

using Posta.Clients;
using Posta.Models.Emails;

using var client = new PostaClient(
    "https://posta.example.com",
    "your-api-key");

SendAnEmailResponse? response = await client.Emails.SendAnEmailAsync(
    new SendAnEmailRequest
    {
        From = "Acme <hello@example.com>",
        To = ["user@example.com"],
        Subject = "Hello from Posta",
        Html = "<h1>Hello!</h1>"
    });

The client exposes typed API areas such as Emails, Templates, Campaigns, Subscribers, Inbound, Webhooks, Workspaces, and Admin.

Known string values

Properties backed by a fixed set of API values remain strings for forward compatibility. The Posta.Models.Constants namespace provides constants for discoverability and to avoid string literals:

using Posta.Models.Constants;

if (verificationResponse.Data?.Status == EmailVerificationStatuses.Valid)
{
    Console.WriteLine("The email address is valid.");
}

The available constant groups are:

• EmailVerificationStatuses: Valid, Invalid, Risky, Disposable, and Unknown
• UserRoles: Admin and User
• WebhookEvents: supported email and campaign webhook events
• SmtpSecurityModes: Permissive and Strict
• ApiKeyScopes: Send, Read, Webhooks, and All
• BounceTypes: Hard and Soft

They can also be used when constructing requests:

using Posta.Models.Constants;
using Posta.Models.Webhooks;

var request = new CreateWebhookRequest
{
    Url = "https://example.com/webhooks/posta",
    Events = [WebhookEvents.EmailSent, WebhookEvents.EmailFailed]
};

Configuration

Use PostaClientSettings when API-key and JWT credentials, a custom timeout, or late-bound configuration are needed:

using Posta.Clients;
using Posta.Configuration;

using var client = new PostaClient(new PostaClientSettings
{
    Endpoint = new Uri("https://posta.example.com"),
    ApiKey = "your-api-key",
    AccessToken = "optional-jwt-access-token",
    Timeout = TimeSpan.FromSeconds(30)
});

An application that manages HttpClient itself can use the constructor accepting HttpClient, IPostaCredentialProvider, and an optional custom IPostaEndpoints catalog.

Aspire integration

Install the optional client-integration package in the service that calls Posta:

dotnet add package Posta.Aspire

Register the client using the same resource name passed from the AppHost with WithReference(...):

builder.AddPostaClient("posta", settings =>
{
    settings.ApiKey = builder.Configuration["Posta:ApiKey"];
});

Resolve IPostaClient from dependency injection. Posta.Aspire reads the Aspire connection string, configures HttpClient, and enables service discovery for the logical posta host name.

Multiple Posta resources can be registered with AddKeyedPostaClient(...) and resolved through GetRequiredKeyedService<IPostaClient>(key).

Error handling

Non-successful HTTP responses throw PostaApiException. The exception contains the HTTP status code and the response body returned by Posta.

using Posta.Transport;

try
{
    await client.Emails.GetEmailDetailsAsync(
        new GetEmailDetailsRequest { Id = emailId });
}
catch (PostaApiException exception)
{
    Console.WriteLine(exception.StatusCode);
    Console.WriteLine(exception.ResponseBody);
    Console.WriteLine(exception.Error?.Code);
    Console.WriteLine(exception.Error?.Type);
    Console.WriteLine(exception.Error?.Message);
}

When an ILoggerFactory is supplied to PostaClient, non-successful responses are logged with structured properties. Client errors, including 401, 404, and 429, use Warning; 5xx responses use Error. Aspire registration uses the application's logger factory automatically. Response bodies are not written to logs.

Custom endpoints

Endpoint definitions are virtual so deployments with custom routes can override only the required operation:

using Posta.Endpoints;

public sealed class CustomPostaEndpoints : PostaEndpoints
{
    public override PostaEndpoint SendAnEmail { get; } =
        new(HttpMethod.Post, "/custom/v1/emails/send", PostaAuthentication.ApiKey);
}

API coverage

The models and operations follow Posta 0.11.0's published OpenAPI document. A few operations whose wire formats are incomplete in that document are present but marked unsupported: CSV subscriber import, HTML template import, raw RFC 5322 message download, and inbound attachment download.

• Posta documentation
• Posta API reference
• Posta OpenAPI document

Building NuGet packages

On Windows:

pack-nuget.bat

On Linux or macOS:

bash ./pack-nuget.sh

Both scripts create the Posta and Posta.Aspire packages in the artifacts directory.

Tests

Run the xUnit test suite from the repository root:

dotnet test Posta.Tests/Posta.Tests.csproj

License

Apache-2.0