CosmoMail 2.0.4

CosmoMail

CosmoMail is a lightweight .NET 10 SMTP/IMAP stack built around direct socket transport, fluent message composition, MIME generation, inbox access, and Fluid-based templating.

It supports plain text and HTML bodies, attachments, inline images, STARTTLS, SMTP authentication including XOAUTH2, capability-aware SMTP sends (SIZE, PIPELINING, SMTPUTF8), reusable message/template objects for high-throughput send paths, lightweight IMAP inbox access including IDLE, mailbox/message management operations, and chunked/streaming MIME fetch support, decoded message-content fetches, and attachment extraction for downloads.

Features

• Direct SMTP transport over sockets and System.IO.Pipelines
• Fluent message builder for sender, recipients, headers, priority, text, and HTML
• MIME generation for multipart/alternative, multipart/mixed, and multipart/related
• Attachments and inline images with base64 encoding
• STARTTLS and PLAIN / LOGIN / XOAUTH2 authentication helpers
• Capability-aware SMTP send flow with SIZE, PIPELINING, and SMTPUTF8 support
• Lightweight IMAP client for inbox login, mailbox selection, IDLE, mailbox list/create/delete/rename, message copy/move, partial/streaming raw message fetch, header listing, decoded message fetch, attachment extraction, read-state updates, and LOGIN / XOAUTH2 authentication
• Fluid template support for reusable subject, text, and HTML rendering
• UTF-8-safe header/body handling and structural response validation
• Cached payload and envelope reuse for repeated sends of the same message

Usage

Simple Send

using CosmoMail;

var message = new SmtpMessage()
    .SetFrom("admin@company.com", "System Admin")
    .AddTo("vip@customer.com", "Important User")
    .AddCc("logs@company.com")
    .SetHighPriority()
    .SetSubject("Daily Analytics Snapshot")
    .SetBody("This is your raw system fallback output.")
    .SetHtmlBody("<h1>Daily Snapshot</h1><p>Welcome back!</p>");

await using var client = new CosmoMailClient("localhost", debug: true);

await client.ConnectAsync("mail.yourserver.com", 587);
await client.EhloAsync();
await client.StartTlsAsync("mail.yourserver.com");
await client.EhloAsync(); // Re-announce capabilities inside the TLS boundary
await client.AuthenticateAsync("LOGIN", "username", "secure_password");

await client.SendMessageAsync(message);
await client.QuitAsync();

Web UI

CosmoMailUI is the active browser UI for this repo. It is a Nuxt-based frontend backed by the CosmoMailUI .NET host and replaces the older Blazor management app.

For development, run the combined host from CosmoMailUI:

cd CosmoMailUI
dotnet run

For deployment or when you explicitly want the host and frontend managed separately, run them in separate terminals:

cd CosmoMailUI
dotnet run

cd CosmoMailUI/frontend
npm run dev

Default URLs:

http://localhost:3000/welcome
http://127.0.0.1:9183

Current UI capabilities include:

• Login against saved mail server configurations
• Register multiple SMTP/IMAP servers from the modal UI with create, edit, and delete flows, including SMTP/IMAP auth mode selection and saved OAuth access tokens
• Gmail-style compose/reply modal with minimize, maximize, attachments, and rich-text editing
• Inbox auto-refresh using IMAP IDLE-backed watch requests while the mailbox view is active
• Mailbox selection plus create, rename, delete, copy, and move flows in the inbox UI
• Automatic seen-state updates when opening a message
• Gmail-style NEW badges for newly arrived unread messages
• Inbox attachment download buttons for message attachments

Templates, Inline Images, and Attachments

using CosmoMail;

var template = new SmtpTemplate(
    subject: "Hello {{ Name }}! Your bill is ready.",
    html: @"
        <h1>Hey {{ Name }}!</h1>
        <p>Attached is your formal receipt generated at {{ Time }}.</p>
        <img src='cid:system-logo' alt='Company Logo' />"
);

var message = await template.RenderAsync(new { 
    Name = "John", 
    Time = DateTime.Now.ToString("F", System.Globalization.CultureInfo.InvariantCulture) 
});

message.SetFrom("billing@company.com", "Billing Dept")
       .AddTo("john.doe@company.com", "John Doe");

byte[] logoBytes = File.ReadAllBytes("logo.jpg");
message.WithInlineImage("system-logo", logoBytes, "image/jpeg");

byte[] pdfBytes = File.ReadAllBytes("receipt.pdf");
message.WithAttachment("receipt_2026.pdf", pdfBytes, "application/pdf");

// Transmit via `SendMessageAsync(message)`...

IMAP Inbox Access

using CosmoMail;

await using var imap = new CosmoImapClient("localhost", debug: false);

await imap.ConnectAsync("mail.yourserver.com", 143);
await imap.StartTlsAsync("mail.yourserver.com");
await imap.LoginAsync("username", "secure_password");

var mailbox = await imap.SelectMailboxAsync("INBOX");
var messages = await imap.ListMessageSummariesAsync(25);

foreach (var message in messages)
{
    Console.WriteLine($"{message.Date:u} {message.From} {message.Subject}");
}

await imap.LogoutAsync();

Testing & Confidence

CosmoMail.Tests uses mock TcpListener-based SMTP and IMAP servers to validate transport commands, EHLO capability parsing, SMTP extension handling, IMAP IDLE, mailbox operations, partial/streaming fetch behavior, UTF-8-safe payload generation, MIME structure, and failure paths.

The current suite contains 64 xUnit tests.

dotnet test

MailKit Parity

CosmoMail is not a full MailKit replacement. It targets a narrower subset of mail workflows with a smaller API surface and less protocol breadth.

Current practical parity looks like this:

Use CosmoMail when you want a small, direct .NET mail stack for the supported scenarios. Use MailKit when you need broad protocol coverage, richer MIME handling, or compatibility with a wider range of server capabilities.

Benchmarks

CosmoMail.Benchmarks contains three benchmark suites:

• SMTP transport benchmarks that compare CosmoMailClient against MailKit using an in-process fake SMTP server
• IMAP inbox benchmarks that compare CosmoImapClient against MailKit for lightweight inbox operations
• template rendering benchmarks that measure SmtpTemplate render + MIME build cost directly

dotnet run -c Release --project CosmoMail.Benchmarks/CosmoMail.Benchmarks.csproj

For a fast in-process comparison without the full BenchmarkDotNet run:

dotnet run -c Release --project CosmoMail.Benchmarks/CosmoMail.Benchmarks.csproj -- --quick

The SMTP benchmark suite currently covers seven scenarios:

• SimpleText: one plain-text message on a fresh connection
• HeaderHeavy: reply-to, CC, BCC, priority, and custom headers
• RichMime: HTML + text + inline image + attachments
• AuthLogin: SMTP AUTH LOGIN on a plain connection
• AuthPlain: SMTP AUTH PLAIN on a plain connection
• StartTlsLogin: STARTTLS upgrade followed by AUTH LOGIN
• Burst10: ten messages on one reused connection

Each SMTP scenario measures a full end-to-end send flow. Depending on the scenario, that includes:

• ConnectAsync / ConnectAsync
• EHLO
• STARTTLS
• AuthenticateAsync("LOGIN" | "PLAIN") / AuthenticateAsync
• SendMessageAsync / SendAsync
• QUIT / DisconnectAsync

Current stable SMTP BenchmarkDotNet results on this machine:

The IMAP benchmark suite currently covers four scenarios:

• ListSummaries: login, select mailbox, list recent message summaries, logout
• FetchContent: login, select mailbox, fetch and decode one message body, logout
• MarkAsRead: login, select mailbox, add \Seen, logout
• InboxRoundTrip: list summaries, fetch one message body, then mark it read in one session

Current stable IMAP BenchmarkDotNet results on this machine:

Current template render + MIME build results:

Latest generated reports:

• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-report-github.md
• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-report.csv
• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-report.html
• BenchmarkDotNet.Artifacts/results/ImapInboxBenchmarks-report-github.md
• BenchmarkDotNet.Artifacts/results/ImapInboxBenchmarks-report.csv
• BenchmarkDotNet.Artifacts/results/ImapInboxBenchmarks-report.html
• BenchmarkDotNet.Artifacts/results/TemplateRenderBenchmarks-report-github.md
• BenchmarkDotNet.Artifacts/results/TemplateRenderBenchmarks-report.csv
• BenchmarkDotNet.Artifacts/results/TemplateRenderBenchmarks-report.html

Performance Notes

The current implementation includes a few transport and MIME-path optimizations that materially affect the benchmark results:

• Cached UTF-8 wire payloads for repeated sends of the same SmtpMessage
• Cached SMTP envelope commands (MAIL FROM and RCPT TO) for repeated sends
• Direct PipeWriter command writes to avoid extra command-string encoding allocations
• Simple-text fast path for non-multipart messages
• Direct base64 appends into the final MIME builder instead of allocating intermediate base64 strings for each MIME part

These changes matter most for:

• SimpleText, where transport overhead dominates
• RichMime, where MIME serialization and allocation pressure dominate
• Burst10, where reusing the same message across one SMTP session highlights payload and envelope caching