XpresMail.Sdk 1.0.0-beta

XpresMail .NET SDK

The official .NET client for XpresMail, a self-hosted email delivery service. A clean fluent API for sending single, bulk, and scheduled emails; server-side templates; open/click tracking; attachments; CC/BCC; and per-send SMTP — with built-in resilience.

Targets net8.0 and netstandard2.0 (works on .NET Framework 4.6.1+).

✨ Features

• Fluent builders — client.SendEmail().To(..).WithSubject(..).ExecuteAsync()
• Clear exceptions — ValidationException (client-side), ApiException (HTTP), XpresMailException (network/base)
• Sending: raw HTML/text, templates, bulk, scheduling, CC/BCC, attachments, BYO-SMTP
• Template management: create / update / get / list / delete / preview
• Resilience (Polly) on net8.0; automatic X-Correlation-Id propagation
• Health-check integration (net8.0) + PingAsync()

💻 Installation

dotnet add package XpresMail.Sdk

⚙️ Configuration

using XpresMail.Sdk;

builder.Services.AddXpresMail(options =>
{
    options.BaseUrl = "https://mail.internal.company.com";
    options.ApiKey  = "xm_xxxxxxxxxxxxxxxxxxxx";
});

// or the short form:
builder.Services.AddXpresMail("https://mail.internal.company.com", "xm_xxxx");

Inject IXpresMailClient anywhere.

🚀 Quickstart

public class WelcomeService(IXpresMailClient mail)
{
    public async Task SendAsync(string to)
    {
        try
        {
            var result = await mail.SendEmail()
                .To(to)
                .WithSubject("Welcome 👋")
                .WithBody("<h1>Hello!</h1>")
                .ExecuteAsync();

            // result.EmailId — track status later.
        }
        catch (ValidationException ex)   { /* bad input before sending */ }
        catch (ApiException ex)          { /* ex.StatusCode, ex.Message */ }
        catch (XpresMailException ex)    { /* network/timeout */ }
    }
}

📨 Sending

// Template + data
await mail.SendEmail()
    .To("kwame@example.com")
    .UseTemplate("welcome", new Dictionary<string, object?> { ["name"] = "Kwame" })
    .ExecuteAsync();

// Attachments, CC/BCC, scheduling
await mail.SendEmail()
    .To("a@b.com").Cc("mgr@b.com").Bcc("audit@b.com")
    .WithSubject("Invoice").WithBody("<p>See attached</p>")
    .AttachFile("invoice.pdf")
    .ScheduleAt(DateTime.UtcNow.AddHours(2))
    .ExecuteAsync();

// Bring your own SMTP
await mail.SendEmail()
    .To("customer@example.com").From("billing@myapp.com")
    .WithSubject("Receipt").WithBody("...")
    .UseSmtp("smtp.myapp.com", port: 465, useSsl: true, user: "billing@myapp.com", password: "••••")
    .ExecuteAsync();

// Bulk with per-recipient data
await mail.SendBulk()
    .UseTemplate("newsletter")
    .AddRecipient("a@x.com", new Dictionary<string, object?> { ["name"] = "Ama" })
    .AddRecipient("b@x.com", new Dictionary<string, object?> { ["name"] = "Kojo" })
    .ExecuteAsync();

🔎 Status, events, list, resend

var status = await mail.GetEmailStatus().WithId(id).ExecuteAsync();
var events = await mail.GetEmailEvents().WithId(id).ExecuteAsync();
var page   = await mail.ListEmails().WithStatus("Failed").WithPage(1).ExecuteAsync();
await mail.ResendEmail().WithId(id).ExecuteAsync();

🧩 Templates

await mail.CreateTemplate().Named("welcome")
    .WithSubject("Welcome, {{ name }}!").WithBody("<h1>Hello {{ name }}</h1>")
    .ExecuteAsync();

var preview = await mail.PreviewTemplate().Named("welcome")
    .WithData("name", "Kwame").ExecuteAsync();

var all = await mail.ListTemplates().ExecuteAsync();
await mail.DeleteTemplate().Named("welcome").ExecuteAsync();

✅ Error handling

❤️ Health checks (net8.0)

builder.Services.AddHealthChecks().AddXpresMail();
bool up = await mail.PingAsync();

📜 License

MIT.