CodeLogic.Mail 4.6.72

This package has a SemVer 2.0.0 package version: 4.6.72+5b7568e.

dotnet add package CodeLogic.Mail --version 4.6.72

NuGet\Install-Package CodeLogic.Mail -Version 4.6.72

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CodeLogic.Mail" Version="4.6.72" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CodeLogic.Mail" Version="4.6.72" />
                    

                            Directory.Packages.props

<PackageReference Include="CodeLogic.Mail" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CodeLogic.Mail --version 4.6.72

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CodeLogic.Mail, 4.6.72"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CodeLogic.Mail@4.6.72

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CodeLogic.Mail&version=4.6.72
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeLogic.Mail&version=4.6.72
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeLogic.Mail

SMTP sending and IMAP reading for CodeLogic 4 — with a built-in template engine, attachments, and RFC 2177 IDLE push notifications.

Compose messages with a fluent MailBuilder, send them over SMTP, render variable-substitution templates (conditionals, loops, and layouts), and read mailboxes over IMAP — including live IDLE push. Built on MailKit and MimeKit. Every fallible operation returns a MailResult / MailResult<T> carrying a categorised MailError instead of throwing on protocol, auth, or timeout errors.

Install

dotnet add package CodeLogic.Mail

Quick start

using CL.Mail;

await Libraries.LoadAsync<MailLibrary>();
await CodeLogic.ConfigureAsync();
await CodeLogic.StartAsync();

var mail = Libraries.Get<MailLibrary>();

// Compose with the fluent builder and send via SMTP.
var message = mail.CreateMessage()
    .From("noreply@example.com", "My App")
    .To("user@example.com")
    .Subject("Welcome!")
    .HtmlBody("<h1>Hello</h1><p>Welcome aboard.</p>")
    .TextBody("Hello — welcome aboard.")
    .Build();

MailResult result = await mail.Smtp.SendAsync(message);
if (!result.IsSuccess)
    Console.WriteLine($"Send failed ({result.Error}): {result.ErrorMessage}");

Features

SMTP sending — plain-text and/or HTML bodies, CC/BCC, attachments, custom headers, and message priority. A fresh connection is opened per send (no pooling).
Fluent MailBuilder — mail.CreateMessage() composes an immutable MailMessage; Build() throws if sender, recipients, subject, or a body are missing.
Template engine — JSON-backed templates with {{var}} / ${var} / {var} substitution, {{#if}}…{{#else}}…{{/if}} conditionals, {{#each}}…{{/each}} loops, and {{#section}} / layout composition.
Templated send — SendTemplatedAsync renders a template by id and sends it in one call.
IMAP reading — list folders, fetch and page messages, fetch by UID with attachments, search, move/copy/delete, and add/remove flags.
IMAP IDLE — RFC 2177 push notifications via StartIdleAsync and the NewMailReceived event.
Result-based errors — MailResult / MailResult<T> carry IsSuccess, a categorised MailError, an ErrorMessage, and a MessageId.

Configuration

Auto-generated on first run as config.mail.json. The Imap section is optional — omit it to disable IMAP entirely.

{
  "Enabled": true,
  "Smtp": {
    "Host": "smtp.example.com",
    "Port": 587,
    "Username": "noreply@example.com",
    "Password": "your-password-or-app-password",
    "SecurityMode": "StartTls",
    "TimeoutSeconds": 30
  },
  "Imap": {
    "Host": "imap.example.com",
    "Port": 993,
    "Username": "inbox@example.com",
    "Password": "your-password-or-app-password",
    "SecurityMode": "SslTls",
    "TimeoutSeconds": 30,
    "EnableIdle": false,
    "IdleRefreshMinutes": 25
  },
  "DefaultFromEmail": "noreply@example.com",
  "DefaultFromName": "My App",
  "TemplateDirectory": "templates"
}

Setting	Default	Description
`Enabled`	`true`	Master switch; when `false` the services aren't created and health reports disabled.
`Smtp.Host` / `Smtp.Port`	`smtp.example.com` / `587`	SMTP server and port.
`Smtp.Username` / `Smtp.Password`	`""`	SMTP credentials (use an app password where required).
`Smtp.SecurityMode`	`StartTls`	`None`, `StartTls` (STARTTLS, port 587), or `SslTls` (implicit TLS, port 465).
`Smtp.TimeoutSeconds`	`30`	SMTP connect/operation timeout.
`Imap`	`null`	Optional; omit the whole section to disable IMAP.
`Imap.SecurityMode`	`SslTls`	`None`, `StartTls`, or `SslTls` (implicit TLS, port 993).
`Imap.EnableIdle`	`false`	Enable RFC 2177 IDLE push monitoring.
`Imap.IdleRefreshMinutes`	`25`	IDLE connection refresh interval (1–28; keep under 29).
`DefaultFromEmail` / `DefaultFromName`	`null`	Fallback sender when a message omits `From`.
`TemplateDirectory`	`templates`	Template folder; relative to the library data dir unless absolute.

Documentation

Full guide: CL.Mail documentation

Requirements

CodeLogic 4 · .NET 10
MailKit 4.x · MimeKit 4.x

License

MIT — see LICENSE.

Product	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.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- CodeLogic (>= 4.0.0 && < 5.0.0)
- MailKit (>= 4.17.0)
- MimeKit (>= 4.17.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
4.6.72	197	6/20/2026
4.6.69-preview	39	6/20/2026
4.5.2	106	5/24/2026
4.5.2-preview.68	60	6/20/2026
4.5.1	158	5/24/2026
4.5.1-preview.56	89	5/24/2026
4.4.2-preview.53	58	5/24/2026
4.4.1	105	5/24/2026
4.0.5	102	5/15/2026
4.0.4	110	5/9/2026
4.0.3	114	5/9/2026
3.3.1	619	4/18/2026
3.3.0	117	4/18/2026
3.2.11	119	4/18/2026
3.2.10	117	4/18/2026
3.2.9	110	4/18/2026
3.2.8	104	4/18/2026
3.2.7	104	4/18/2026
3.2.6	109	4/18/2026
3.2.5	106	4/18/2026

# CL.Mail — Changelog

All notable changes to **CodeLogic.Mail** are documented here. Versions follow
[Semantic Versioning](https://semver.org/).

## 2026-06-20

### Documentation

- Full rewrite of the README and the multi-page docs set to the CodeLogic.Libs
house style. The README is now concise, Markdown-only, and NuGet-safe; the
guide is split into **Overview & Sending** (`docs/libs/mail/index.md`) and
**Receiving & Templates** (`docs/libs/mail/receiving-templates.md`), with the
old `docs/libs/mail.md` reduced to a redirect stub and the docs navigation
updated accordingly. No API changes.

## [4.5.1] — 2026-06-20

### Documentation

- Rewrote the README and the Mail & Templates guide to match the current public
API. The previous docs described members that no longer exist (`EmailMessage`,
`EmailAttachment`, `ReplyTo`, `RenderTemplateAsync`, `ReadInboxAsync`,
`ImapFilter`, `MarkAsReadAsync`, the `SendAsync(from:, to:, …)` /
`SendTemplateAsync` overloads, and the `UseSsl` / `FromAddress` config keys).
- Documented the real surface: the fluent `MailBuilder` (`CreateMessage()`),
`SmtpService.SendAsync(MailMessage)`, `MailLibrary.SendTemplatedAsync`, the
`MailResult` / `MailError` result model, and the JSON-backed template system
(`MailTemplate`, `IMailTemplateProvider`, `IMailTemplateEngine`).
- Documented previously undocumented features: template conditionals
(`{{#if}}`/`{{#else}}`), loops (`{{#each}}`), sections and layouts; the
`${var}` / `{var}` placeholder syntaxes; the full IMAP API (fetch/page, fetch
by UID, search via `ImapSearchCriteria`, move/copy/delete, flag operations,
folder management); and RFC 2177 IMAP IDLE push (`StartIdleAsync` /
`NewMailReceived`) with its `EnableIdle` / `IdleRefreshMinutes` config keys.
- Corrected the documented config schema and `SecurityMode` values
(`None` / `StartTls` / `SslTls`).

## [4.5.0] — 2026-05-24

### Changed

- **Unified versioning.** All CodeLogic.Libs now share a single version line
controlled by `version.txt` in the repo root. This is a version alignment
release — no functional changes to this library.
## [4.0.4] — 2026-04-16

### Changed

- README + manifest refresh for the v4 baseline. No functional changes vs 4.0.3.
- `LibraryManifest.Version` now reads from assembly metadata.

## [4.0.2] — 2026-04-09

### Changed

- Annotated mail configuration with `[ConfigField]` for the admin UI surface.
- Aligned with the v4 baseline across all libraries.

### Fixed

- Resolved null-reference warnings in `ImapService`.

## [4.0.0] — 2026-04-09

Major rewrite. Republished as v4.0.0 to reset the version line under the
unified v4 baseline. SMTP / IMAP services + a CodeLogic-native template
provider.

### Notes

- Earlier history is retained in the
[git log](https://github.com/Media2A/CodeLogic.Libs/commits/main/CL.Mail).