Edi.TemplateEmail.Smtp
2026.8.0
dotnet add package Edi.TemplateEmail.Smtp --version 2026.8.0
NuGet\Install-Package Edi.TemplateEmail.Smtp -Version 2026.8.0
<PackageReference Include="Edi.TemplateEmail.Smtp" Version="2026.8.0" />
<PackageVersion Include="Edi.TemplateEmail.Smtp" Version="2026.8.0" />
<PackageReference Include="Edi.TemplateEmail.Smtp" />
paket add Edi.TemplateEmail.Smtp --version 2026.8.0
#r "nuget: Edi.TemplateEmail.Smtp, 2026.8.0"
#:package Edi.TemplateEmail.Smtp@2026.8.0
#addin nuget:?package=Edi.TemplateEmail.Smtp&version=2026.8.0
#tool nuget:?package=Edi.TemplateEmail.Smtp&version=2026.8.0
Edi.TemplateEmail
Build email messages from XML templates in .NET 10. Edi.TemplateEmail handles templates and token mapping; Edi.TemplateEmail.Smtp adds SMTP delivery through MailKit.
Install
dotnet add package Edi.TemplateEmail
# Optional SMTP delivery
dotnet add package Edi.TemplateEmail.Smtp
XML templates
Place mailConfiguration.xml in your application's output/deployment directory, or supply another path to EmailHelper.
<?xml version="1.0"?>
<MailConfiguration>
<MailMessage MessageType="Welcome" IsHtml="true">
<MessageSubject>Welcome, {User.Name}</MessageSubject>
<MessageBody><![CDATA[
<p>Hello {User.Name}!</p>
<p>{Message.Value}</p>
{Footer.Value}
]]></MessageBody>
</MailMessage>
</MailConfiguration>
MessageType and IsHtml are attributes; MessageSubject, MessageBody, and optional MessageCulture are elements. Use IsHtml="false" for plain text.
Without an explicit culture, template selection matches MessageType exactly, prefers a case-insensitive match between MessageCulture and CultureInfo.CurrentCulture.Name, and otherwise uses the first entry of that message type.
Both EmailHelper constructors validate configuration when the helper is created. MessageType must be nonblank; MessageSubject and MessageBody must be present and non-null. Empty strings are allowed: use <MessageSubject /> or <MessageBody /> for intentionally empty content. MessageCulture remains optional, and omitted IsHtml still defaults to false. A null configuration, null MailMessages list, or null template entry is rejected; an empty list remains valid.
Each MessageType/MessageCulture pair must be unique. Types are compared ordinally with case sensitivity; cultures use a case-insensitive invariant comparison. An omitted or empty culture represents the same key. Configuration errors identify the zero-based template index, type and culture where available, and the invalid field or duplicate key.
Migration note: helpers now reject invalid configuration at construction instead of failing during message building or silently selecting the first duplicate. Null configuration throws ArgumentNullException; invalid fields, lists, entries, or duplicate keys throw InvalidOperationException. Supply missing subject/body elements and remove duplicate keys before upgrading. With DI, validation occurs when IEmailHelper is resolved. Validation does not copy or freeze the configuration or revalidate later mutations; keep subsequent edits valid. Template selection and engine creation remain deferred until BuildMessage.
Build a message
using Edi.TemplateEmail;
var configPath = Path.Combine(AppContext.BaseDirectory, "mailConfiguration.xml");
var emailHelper = new EmailHelper(configPath);
var message = emailHelper.ForType("Welcome")
.Map("User", new { Name = "Alice & Bob" })
.MapRange(
("Message", "Your account is ready."),
("Footer", new TrustedHtml("<small>Example team</small>")))
.BuildMessage(["alice@example.com"]);
ForType creates an independent IEmailBuilder; Map and MapRange return that builder. Template selection and rendering occur at BuildMessage. You can also construct EmailHelper from a MailConfiguration instance.
BuildMessage(to, cc) requires at least one To recipient, accepts optional CC recipients, copies both arrays, and trims the rendered subject and body. The resulting CommonMailMessage remains mutable.
Separate builders from the same helper can be interleaved or built in parallel. Use one builder per message; do not use the same builder concurrently or mutate shared configuration or mapped objects during builds.
Recipient culture
Pass the recipient's CultureInfo to ForType to select and format a message independently of CurrentCulture. Use the existing XML shape for localized templates and an entry without MessageCulture (or with an empty element) as the explicit default:
<MailConfiguration>
<MailMessage MessageType="Invoice" IsHtml="false">
<MessageSubject>Invoice {Invoice.Number}</MessageSubject>
<MessageBody>Total: {Invoice.Total}, date: {Invoice.Date}</MessageBody>
</MailMessage>
<MailMessage MessageType="Invoice" IsHtml="false">
<MessageCulture>fr</MessageCulture>
<MessageSubject>Facture {Invoice.Number}</MessageSubject>
<MessageBody>Total : {Invoice.Total}, date : {Invoice.Date}</MessageBody>
</MailMessage>
</MailConfiguration>
using System.Globalization;
var message = emailHelper.ForType("Invoice", CultureInfo.GetCultureInfo("fr-CA"))
.Map("Invoice", new { Number = 42, Total = 1234.5m, Date = new DateTime(2026, 11, 5) })
.BuildMessage(["alice@example.com"]);
Selection tries the exact culture, each parent culture in order, then the explicit default. In this example fr-CA uses the fr template; add a fr-CA entry to override it. Culture names are compared without case sensitivity, while message types remain case-sensitive. CultureInfo.InvariantCulture selects only the default. If neither a match nor a default exists, BuildMessage throws InvalidOperationException identifying the type and requested culture. The built-in helper rejects a null culture with ArgumentNullException.
Dates, numbers, and other IFormattable values use ToString(null, culture), both for whole mapped values and object properties. Formatting always uses the requested culture, even when the template comes from a parent or the default. Other values retain their custom ToString() behavior. No ambient culture is changed; use independent builders for different recipients and do not mutate the supplied culture during builds.
Compatibility note: ForType(mailType) retains its existing selection and formatting behavior, including first-entry fallback. Template selection and engine creation remain deferred until BuildMessage for both overloads. Existing third-party IEmailHelper implementations can keep their original method; the new overload has a default implementation that throws NotSupportedException until they implement explicit culture support. IEmailBuilder is unchanged.
Token mapping
- Tokens use
{Entity.Property}with case-sensitive names; both parts match\w+. {Entity.Value}formats the entire mapped value, using itsToString()or culture-aware formatting when an explicit culture is supplied.Valueis reserved, including when the mapped object has a property with that name. Map that property's value separately to render it.- Other property names resolve public, readable, non-indexed instance properties. Strings return the same string for any property name; values without public properties fall back to
ToString(). - Missing entities/properties, unsupported properties, and null values render as empty strings. Exceptions from readable getters propagate.
- Without an explicit culture, dates and numbers use their normal
ToString()behavior and the current culture where applicable. With an explicit culture,IFormattablevalues use that culture as described above.
HTML values
HTML bodies encode ordinary mapped values, including object properties, while preserving the XML template's markup. Subjects and plain-text bodies use the mapped text directly. Supply ordinary text without pre-encoding to avoid double encoding.
TrustedHtml explicitly inserts a complete mapped fragment without encoding, as shown by Footer above. Use only trusted or sanitized markup: this wrapper does not sanitize its input. Map fragments separately as {Entity.Value}; a wrapper inside an ordinary object's property remains encoded. MapRange also accepts TrustedHtml.
Keep ordinary tokens in HTML text or quoted attributes. The renderer does not parse HTML contexts; do not insert untrusted values into tag names, unquoted attributes, event handlers, styles, or executable content. Validate URL schemes and destinations before mapping URL attributes, applying your application's host, port, and path rules. HTML encoding does not validate URLs; encode URL components separately when constructing them.
Direct TemplateEngine.Format(text) calls perform unencoded token replacement. Use Format(text, encodeHtml: true) to encode ordinary values when rendering HTML directly.
SMTP delivery
Install Edi.TemplateEmail.Smtp and configure the sender and SMTP connection:
using Edi.TemplateEmail.Smtp;
using MailKit.Security;
var emailSettings = new EmailSettings
{
FromAddress = "notifications@example.com",
EmailDisplayName = "Example team",
SmtpSettings = new(
"smtp.example.com",
Environment.GetEnvironmentVariable("SMTP_USER"),
Environment.GetEnvironmentVariable("SMTP_PASSWORD"),
587)
{
SocketOptions = SecureSocketOptions.StartTls
}
};
var response = await message.SendAsync(emailSettings);
FromAddress is required and independent of the SMTP login. A null or empty SMTP user name skips authentication. Optional SenderAddress and SenderName set the Sender header when sending on behalf of another address; EmailDisplayName names the From address.
Before connecting or authenticating, SendAsync validates the settings and completes MIME conversion, including address parsing. SMTP settings require a nonblank server, a port from 0 through 65535, a defined SecureSocketOptions value, and a non-null password when a user name is supplied (an empty password is allowed). Port 0 retains MailKit's default-port selection. At least one To recipient is required; optional CC entries must also parse as mailbox addresses. Address parsing checks syntax, not whether a mailbox exists.
Migration note: invalid input now fails before any SMTP connection, so input errors can take precedence over connection or authentication errors. Null inputs and missing To recipients produce argument exceptions instead of failing later during conversion or sending. Correct invalid settings or addresses before retrying; ToMimeMessage still works without SMTP settings.
Choose SmtpSettings.SocketOptions for your server:
| Mode | Behavior |
|---|---|
StartTls (default) |
Requires STARTTLS; commonly used on port 587. |
SslOnConnect |
Uses TLS immediately; commonly used on port 465. |
None |
Unencrypted connection. |
StartTlsWhenAvailable |
Uses STARTTLS when supported, otherwise permits unencrypted delivery. |
Auto |
Uses SslOnConnect on port 465 and StartTlsWhenAvailable on other ports. |
Choose StartTls or SslOnConnect when encryption is required. SkipCertificateValidation defaults to false; enable it only in development.
SendAsync accepts an optional cancellation token for connection, authentication, and sending. It returns the SMTP acceptance response; downstream delivery can still fail. Cleanup attempts graceful disconnection without the caller's token and always attempts disposal. Cleanup failures and cancellation after successful sending do not replace the response or an original operation exception.
The library does not retry automatically. A send failure or cancellation can leave acceptance uncertain, so callers must account for possible duplicates when retrying. See the MailKit documentation.
Dependency injection
Register on your application's IServiceCollection:
using Edi.TemplateEmail.Smtp;
using Microsoft.Extensions.DependencyInjection;
services.AddTemplateEmail(configPath, settings =>
{
settings.FromAddress = "notifications@example.com";
settings.SmtpSettings = new("smtp.example.com", null, null, 587);
});
Inject IEmailHelper and EmailSettings, and call ForType for each message. The helper is transient, settings are singleton, and builders are created per call rather than registered as shared services. The example uses anonymous SMTP; set credentials as needed.
The file-path overload reads XML each time a helper is resolved. New helpers see file edits; existing helpers and their builders keep the configuration they loaded. A missing file fails the next resolution.
For frequent helper resolution or large template files, load XML once during application setup and use the existing MailConfiguration overload:
using Edi.TemplateEmail;
using System.Xml.Serialization;
MailConfiguration configuration;
using (var stream = File.OpenRead(configPath))
{
configuration = (MailConfiguration)new XmlSerializer(typeof(MailConfiguration)).Deserialize(stream);
}
services.AddTemplateEmail(configuration, settings =>
{
settings.FromAddress = "notifications@example.com";
settings.SmtpSettings = new("smtp.example.com", null, null, 587);
});
Helpers remain transient and validate the shared configuration when resolved; each ForType still creates an independent builder. The configuration is shared without copying or freezing, so treat it as read-only during use. File edits or deletion do not affect this registration. To adopt a new snapshot, deserialize a fresh configuration and create a new registration/provider, for example on application restart; existing helpers keep the original instance. There is no library-managed cache, file watcher, or automatic reload.
Interactive sample
The console sample reads mailConfiguration.xml from the current working directory using Path.Combine. To run it on Windows, Linux, or macOS, start from the repository root:
cd src/Edi.TemplateEmail.TestConsole
dotnet run --configuration Release
When launching the compiled sample instead, use its output directory as the working directory; the build copies mailConfiguration.xml there. The sample prompts for SMTP settings and sends a real email, so run it manually rather than as an automated test.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Edi.TemplateEmail (>= 2026.8.0)
- MailKit (>= 4.18.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.