CosmoSmtp 1.0.2

CosmoSmtp

CosmoSmtp is a lightweight .NET 10 SMTP client and MIME generation library built around direct socket transport, fluent message composition, and Fluid-based templating.

It supports plain text and HTML bodies, attachments, inline images, STARTTLS, SMTP authentication, and reusable message/template objects for high-throughput send paths.

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 authentication helpers
• 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 CosmoSmtp;

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 CosmoSmtpClient("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();

Templates, Inline Images, and Attachments

using CosmoSmtp;

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)`...

Testing & Confidence

CosmoSmtp.Tests uses a mock TcpListener-based SMTP server to validate transport commands, response handling, UTF-8-safe payload generation, MIME structure, and failure paths.

The current suite contains 31 xUnit tests.

dotnet test

Benchmarks

CosmoSmtp.Benchmarks compares CosmoSmtpClient against MailKit for the same local SMTP send flow using an in-process fake SMTP server.

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

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

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

The benchmark project currently covers three scenarios:

• SimpleText: one plain-text message on a fresh connection
• RichMime: HTML + text + inline image + attachments
• Burst10: ten messages on one reused connection

Each scenario measures a full SMTP send flow:

• ConnectAsync / ConnectAsync
• EHLO
• SendMessageAsync / SendAsync
• QUIT / DisconnectAsync

Current stable BenchmarkDotNet results on this machine:

Latest generated reports:

• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-report-github.md
• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-report.csv
• BenchmarkDotNet.Artifacts/results/SmtpSendBenchmarks-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