TailoredApps.Shared.Mediator.Email¶
Description¶
Mediator pipeline integration for email sending. The library provides the SendMail command and its SendMailCommandHandler, making email sending a natural part of CQRS architecture — you can send an email via _mediator.Send(new SendMail { ... }) without a direct dependency on IEmailProvider.
This approach makes it easy to enrich the sending process with logging, retry, and auditing from the pipeline behaviors level, without modifying the handler.
Installation¶
DI registration¶
// Program.cs
using TailoredApps.Shared.Email;
using TailoredApps.Shared.Mediator.Email.Handlers;
using TailoredApps.Shared.Email.MailMessageBuilder;
// 1. Register the email provider (SMTP or console)
builder.Services.RegisterSmtpProvider();
// 2. Register the mail message builder
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.Configure<TokenReplacingMailMessageBuilderOptions>(o =>
{
o.Location = "EmailTemplates/";
o.FileExtension = "html";
});
// 3. Mediator: scan the library assembly as well - that is where SendMailCommandHandler lives
builder.Services.AddMediator(cfg =>
{
cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
cfg.RegisterServicesFromAssembly(typeof(SendMailCommandHandler).Assembly);
});
The package has no registration extension of its own. The mediator resolves the handler as IRequestHandler<SendMail, SendMailResponse>, so registering SendMailCommandHandler only under ISendMailCommandHandler does not let _mediator.Send(new SendMail { ... }) find it. Either scan the library assembly as above or register the handler under the mediator interface yourself:
builder.Services.AddTransient<IRequestHandler<SendMail, SendMailResponse>, SendMailCommandHandler>();
In an application that is trimmed or published with NativeAOT scanning is not available - the handler is registered by name:
builder.Services.AddMediator(cfg =>
cfg.AddRequestHandler<SendMail, SendMailResponse, SendMailCommandHandler>());
The library is NativeAOT-compatible together with the SMTP and console providers of TailoredApps.Shared.Email; the Email.Office365
provider is not. The other rules: Mediator: Trimming and NativeAOT.
Usage example¶
using TailoredApps.Shared.Mediator.Email.Messages.Commands;
public class UserRegistrationService
{
private readonly IMediator _mediator;
public UserRegistrationService(IMediator mediator) => _mediator = mediator;
public async Task RegisterUserAsync(string email, string userName)
{
// Registration logic...
// Send the welcome email through the mediator pipeline
var result = await _mediator.Send(new SendMail
{
Recipent = email,
Subject = "Welcome to our service!",
Template = "welcome.html",
TemplateVariables = new Dictionary<string, string>
{
{ "UserName", userName },
{ "ActivationUrl", $"https://app.example.com/activate/{Guid.NewGuid()}" }
},
Attachments = null
});
Console.WriteLine($"Email sent, MessageId: {result.MessageId}");
}
public async Task SendInvoiceAsync(
string email,
string invoiceNumber,
byte[] pdfContent)
{
await _mediator.Send(new SendMail
{
Recipent = email,
Subject = $"Invoice #{invoiceNumber}",
Template = "invoice.html",
TemplateVariables = new Dictionary<string, string>
{
{ "InvoiceNumber", invoiceNumber }
},
Attachments = new Dictionary<string, byte[]>
{
{ $"invoice_{invoiceNumber}.pdf", pdfContent }
}
});
}
}
API Reference¶
| Type | Kind | Description |
|---|---|---|
SendMail |
Command (IRequest<SendMailResponse>) |
Email data: Recipent, Subject, Template, TemplateVariables, Templates, Attachments |
SendMailResponse |
Class | Send result: MessageId (provider-specific identifier) |
SendMailCommandHandler |
Handler | Builds the body from a template and sends it through IEmailProvider |
ISendMailCommandHandler |
Interface | Handler contract |
🤖 AI Agent Prompt¶
## TailoredApps.Shared.Mediator.Email - instructions for an AI agent
You are using TailoredApps.Shared.Mediator.Email to send emails through the mediator pipeline.
### Registration
```csharp
builder.Services.RegisterSmtpProvider(); // or RegisterConsoleProvider()
builder.Services.AddTransient<IMailMessageBuilder, TokenReplacingMailMessageBuilder>();
builder.Services.AddMediator(cfg =>
{
cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
cfg.RegisterServicesFromAssembly(typeof(SendMailCommandHandler).Assembly); // the SendMail handler
});
```
### Sending an email
```csharp
var result = await _mediator.Send(new SendMail
{
Recipent = "user@example.com",
Subject = "Subject",
Template = "template.html", // template file name
TemplateVariables = new() { { "Name", "Jan" } },
Attachments = null // or Dictionary<string, byte[]>
});
// result.MessageId — the ID assigned by the provider
```
### Rules
- The mediator must find the handler as IRequestHandler<SendMail, SendMailResponse>: scan the library assembly; registering it only as ISendMailCommandHandler is not enough
- Template and Recipent are required - the handler throws ArgumentException when either is null
- Template is the template key passed to IMailMessageBuilder.Build()
- TemplateVariables replace {{token}} in the template
- Provide Templates (Dictionary<string,string>) when the templates are inline, not from a file
- SendMail throws if the template is not found in IMailMessageBuilder
- An application with PublishAot: instead of scanning, cfg.AddRequestHandler<SendMail, SendMailResponse, SendMailCommandHandler>(); the Email.Office365 provider is not NativeAOT-compatible