Decode.Email.Abstractions 2.0.1

Decode.Email.Abstractions

Core contracts, models, and HTML template engine abstractions for email services in the Decode ecosystem.

🚀 Features

• IEmailService: Framework-agnostic interface for sending email messages and HTML templates across Domain and Application layers.
• IEmailTemplateEngine: Built-in template engine supporting both Mustache syntax ({{TAG}}) and Hashtag syntax (#TAG#).
• EmbeddedEmailTemplateProvider: Automatic loading and IMemoryCache caching of embedded .html template resources.
• Provider-Agnostic Models: Unified EmailMessage, EmailAddress, and EmailAttachment models with metadata support.
• Shared Template Registration: AddDecodeEmailEmbeddedTemplates lives here, so it can be used with any provider.

📦 Installation

Add the package to your Domain or Application layer:

dotnet add package Decode.Email.Abstractions

📖 Usage

1. Defining Email Templates in Your Project

Create an HTML template file in your project (e.g. EmailTemplates/Welcome.html):

<div style="font-family: Arial, sans-serif; padding: 20px;">
    <h2>Hello, {{NAME}}!</h2>
    <p>Your verification code is: <strong>#CODE#</strong></p>
    <p>This code expires in {{EXPIRATION}}.</p>
</div>

Ensure the .html file is configured as an Embedded Resource in your .csproj:

<ItemGroup>
  <EmbeddedResource Include="EmailTemplates\*.html" />
</ItemGroup>

2. Injecting IEmailService in Application Handlers

Your Domain Services and Handlers only depend on Decode.Email.Abstractions:

using Decode.Email.Abstractions.Interfaces;
using Decode.Email.Abstractions.Models;

public class RegisterCommandHandler(IEmailService emailService)
{
    public async Task HandleAsync(RegisterUserCommand command, CancellationToken ct)
    {
        // Option A: Send HTML template with anonymous object model
        await emailService.SendTemplateAsync(
            to: new EmailAddress(command.Email, command.Name),
            subject: "Welcome to Our Platform",
            templateName: "Welcome",
            model: new
            {
                NAME = command.Name,
                CODE = "998877",
                EXPIRATION = "15 minutes"
            },
            cancellationToken: ct
        );

        // Option B: Send raw email message directly
        EmailMessage message = new()
        {
            From = new EmailAddress("noreply@mydomain.com", "My Application"),
            To = [new EmailAddress(command.Email, command.Name)],
            Subject = "Account Created",
            BodyHtml = "<h1>Your account is ready!</h1>"
        };

        await emailService.SendAsync(message, ct);
    }
}

✉️ Sender Resolution (changed in 2.0.0)

EmailMessage.From is now EmailAddress?. Leave it unset and the provider uses its configured DefaultFromEmail / DefaultFromName:

EmailMessage message = new()
{
    // From omitted — falls back to DefaultFromEmail
    To = [new EmailAddress(command.Email)],
    Subject = "Account Created",
    BodyHtml = "<h1>Your account is ready!</h1>"
};

The property was previously non-nullable and initialized to an empty address, so it was never null and the providers' message.From ?? DefaultFromEmail fallback was unreachable. Configuring a default sender and omitting From raised "Sender email address (From) is required." instead of using it.

Code that reads message.From.Address must now handle null.

🔤 Template Rendering

Placeholders are substituted in a single left-to-right pass, so a substituted value is never rescanned. Before 2.0.0 replacement ran one key at a time across the whole document, which meant caller-supplied data containing {{ResetLink}} was itself expanded into the real reset link.

Values are inserted verbatim by default, because templates commonly pass HTML fragments as model values. When values come from user input, enable encoding:

builder.Services.Configure<EmailTemplateOptions>(o => o.HtmlEncodeValues = true);

📄 License

This project is licensed under the MIT License.