Katalyst.Core.Email 1.2.1

Katalyst Email

.NET library for sending transactional email through Resend using the official Resend .NET SDK. Configuration binds Email (provider, shared defaults, optional Razor base path, optional queue hints) and Email:Resend (API key), then registers Core.Email.Abstractions.IEmailSender.

The package is structured for additional providers later; today only Resend is implemented.

Requirements

• .NET 10 SDK
• A Resend account and API key

Installation

Add the Katalyst.Core.Email package to your app (NuGet feed or a project reference to Email/Core.Email/Core.Email.csproj).

dotnet add package Katalyst.Core.Email

Resend and domain setup

Before the library can send mail, configure Resend and your sending domain.

1. Create an API key in the Resend dashboard (API Keys). Use a key with permission to send email.
2. Add and verify a domain in Resend (Domains). Complete DNS records (SPF, DKIM, etc.) until the domain shows as verified.
3. Choose a “from” address that uses your verified domain, for example noreply@mail.example.com. Resend will reject or fail sends if the domain is not verified or the address is not allowed for your account.
4. Optional — templates for SendTemplatedAsync: create a template in Resend, publish it, and copy its template UUID from the dashboard.

Official help: Resend documentation.

Configuration

Bindings use two layers:

• Email — provider selection and settings shared across vendors (EmailOptions.SectionName).
• Email:Resend — Resend-specific options (ResendEmailOptions.SectionName).

Example appsettings.json:

{
  "Email": {
    "Provider": "Resend",
    "DefaultFrom": {
      "Address": "noreply@mail.yourdomain.com",
      "Name": "Your App"
    },
    "RazorTemplateBasePath": "Templates",
    "Queue": {
      "Enabled": false,
      "QueueName": "outbound-email"
    },
    "Resend": {
      "ApiKey": "re_xxxxxxxxxxxxxxxxxxxxxxxx",
      "IsApiKeyEncrypted": false
    }
  }
}

Environment variables override JSON when both are loaded (the development tool merges environment variables after the file). Examples:

• Email__Provider
• Email__DefaultFrom__Address
• Email__DefaultFrom__Name
• Email__RazorTemplateBasePath
• Email__Queue__Enabled
• Email__Queue__QueueName
• Email__Resend__ApiKey
• Email__Resend__IsApiKeyEncrypted

ASP.NET Core applications

Use the same Email configuration as in Configuration (typically appsettings.json plus User Secrets or environment variables for the API key in development).

Register services (Program.cs)

With the minimal hosting model, register email right after WebApplication.CreateBuilder:

using Core.Email;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(); // if you use MVC controllers
builder.Services.AddAppEmail(builder.Configuration);

var app = builder.Build();
// …middleware and endpoints…
app.Run();

Options are validated on startup (ValidateOnStart()); a missing or invalid Email:Provider / Resend settings causes the host to fail fast when the service provider is built.

If you still use Startup, call services.AddAppEmail(Configuration) from ConfigureServices.

Example: minimal API endpoint

using Core.Email.Abstractions;
using Core.Email.Models;

app.MapPost("/notify/welcome", async (string to, IEmailSender emailSender, CancellationToken cancellationToken) =>
{
    var message = new RegularMail
    {
        Subject = "Welcome",
        To = [new EmailContact(to)],
        Body = "<p>Thanks for signing up.</p>",
        IsHtml = true,
    };

    var result = await emailSender.SendAsync(message, cancellationToken);
    if (result.Succeeded)
        return Results.Ok();
    if (result.IsQueued)
        return Results.Accepted(); // enqueue using result.BodyContent in your app
    return Results.BadRequest(new { result.Status, result.Reason });
});

Example: MVC API controller

using Core.Email.Abstractions;
using Core.Email.Models;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public sealed class NotificationsController : ControllerBase
{
    private readonly IEmailSender _emailSender;

    public NotificationsController(IEmailSender emailSender) =>
        _emailSender = emailSender;

    [HttpPost("welcome")]
    public async Task<IActionResult> SendWelcome(
        [FromQuery] string to,
        CancellationToken cancellationToken)
    {
        var result = await _emailSender.SendAsync(
            new RegularMail
            {
                Subject = "Welcome",
                To = [new EmailContact(to)],
                Body = "<p>Thanks for signing up.</p>",
                IsHtml = true,
            },
            cancellationToken);

        return result.Succeeded ? Ok()
            : result.IsQueued ? Accepted()
            : BadRequest(new { result.Status, result.Reason });
    }
}

Each send returns EmailResult with Status (see EmailConstants.EmailStatus), optional Reason (provider API error text on failure), the original Message, and when applicable BodyContent / BodyIsHtml (plain or Razor body). Use Succeeded, IsQueued, or compare Status instead of relying on exceptions for normal outcomes.

Using the library (step by step)

1. Add configuration — Add the Email section with Provider, DefaultFrom, nested Resend (ApiKey, and IsApiKeyEncrypted if using plaintext keys). Optionally set Queue if your host enqueues outbound mail itself.

2. Register services — In Program.cs (minimal host) or Startup.ConfigureServices, call AddAppEmail with the root IConfiguration:

   using Core.Email;
   
   builder.Services.AddAppEmail(builder.Configuration);
   

3. Inject IEmailSender — Resolve Core.Email.Abstractions.IEmailSender in constructors, minimal API parameters, or [FromServices] where appropriate.

4. Build a message — Use RegularMail for plain HTML/text, TemplateMail for a published Resend template (template id must be a GUID string), or RazorMail for a local .cshtml template rendered by RazorLight.

5. Send — Call SendAsync, SendTemplatedAsync, or SendRazorTemplatedAsync. For plain sends, Body, Subject, and at least one To recipient are required (use IsHtml to choose HTML vs plain text).

If you omit From on a message, the sender defaults to Email:DefaultFrom.

When Email:Queue:Enabled is true, the library skips the provider call and returns EmailResult.Queued so you can persist or enqueue BodyContent (and honor BodyIsHtml) in your application.

Examples

Namespaces: Core.Email.Abstractions, Core.Email.Models.

Plain HTML and text email

using Core.Email.Abstractions;
using Core.Email.Models;

var message = new RegularMail
{
    Subject = "Welcome",
    To = [new EmailContact("user@example.com", "User Name")],
    Body = "<p>Welcome to the <strong>app</strong>.</p>",
    IsHtml = true,
};

var result = await emailSender.SendAsync(message);

Custom from, CC, and BCC

var message = new RegularMail
{
    Subject = "Invoice ready",
    To = [new EmailContact("customer@example.com")],
    Body = "Your invoice is attached in the portal.",
    From = new EmailContact("billing@mail.yourdomain.com", "Billing"),
    Cc = [new EmailContact("finance@yourdomain.com")],
    Bcc = [new EmailContact("archive@yourdomain.com")],
};

var result = await emailSender.SendAsync(message);

Resend template (published template UUID)

Resend supplies subject and bodies from the template. TemplateMail still requires Subject on BaseMail for the model; use an empty subject — the Resend implementation sets the outbound Subject to empty on the SDK message because the template defines visible content.

var message = new TemplateMail
{
    Subject = string.Empty,
    TemplateId = "00000000-0000-0000-0000-000000000000",
    To = [new EmailContact("user@example.com")],
    TemplateVariables = new Dictionary<string, object>
    {
        ["name"] = "Alex",
        ["resetLink"] = "https://app.example.com/reset?token=...",
    },
};

var result = await emailSender.SendTemplatedAsync(message);

Replace the GUID with your template’s id from the Resend dashboard.

Local Razor .cshtml template (RazorLight)

dynamic model = new
{
    name = "Alex",
    resetLink = "https://app.example.com/reset?token=...",
};

var message = new RazorMail
{
    Subject = "Welcome",
    To = [new EmailContact("user@example.com")],
    TemplatePath = "Welcome.cshtml",
    Data = model,
};

var result = await emailSender.SendRazorTemplatedAsync(message);

Set Email:RazorTemplateBasePath when using relative template paths (they combine with that folder, then resolve to an absolute path). You can also pass a TemplatePath value that is already an absolute file path.

The host registers a singleton IRazorLightEngine with UseFileSystemProject(AppContext.BaseDirectory) and UseMemoryCachingProvider(). After resolution, templates are rendered with CompileRenderAsync(absoluteTemplatePath, model) so compilation and caching stay centralized in RazorLight.

Solution layout

• Email/Core.Email — packable library (NuGet package id: Katalyst.Core.Email): abstractions, models, Resend provider, Razor rendering, optional API-key decryption helpers.
• Email/Email.Utility — development CLI (encrypt, decrypt, send smoke tests; not published as a package).
• Email/Email.slnx — solution file.

Email.Utility sample appsettings.json

The CLI loads Email/Email.Utility/appsettings.json next to the built assembly by default (see Email.Utility README). Structure matches Email binding plus optional Serilog for console logging:

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console" ],
    "MinimumLevel": "Information",
    "WriteTo": [ { "Name": "Console" } ]
  },
  "Email": {
    "Provider": "Resend",
    "Queue": {
      "Enabled": false,
      "QueueName": "app:emails"
    },
    "DefaultFrom": {
      "Address": "noreply@mail.yourdomain.com",
      "Name": "Your App"
    },
    "RazorTemplateBasePath": "Templates",
    "Resend": {
      "ApiKey": "<paste ciphertext>"
    }
  }
}

Use ciphertext as shown (omit IsApiKeyEncrypted so the library decrypts), or for local-only testing set "ApiKey": "re_..." and "IsApiKeyEncrypted": false.

dotnet build Email/Email.slnx