SyntaxCircus.Email 0.1.5

SyntaxCircus.Email

SyntaxCircus.Email is a small .NET email-delivery primitive. It supplies an IEmailSender abstraction with SMTP/MailKit, null/logging, and in-memory implementations. It intentionally does not provide templates, rendering, queueing, delivery tracking, or application-specific message composition.

No support guaranteed. Published as-is and maintained on a best-effort basis. Issues and PRs are welcome, but there is no SLA.

Choose an implementation

Register exactly one IEmailSender implementation for the service provider that sends mail.

Quick start

builder.Services.AddSmtpEmailSender(builder.Configuration);

{
  "Email": {
    "Smtp": {
      "Host": "smtp.example.com",
      "Port": 587,
      "Username": "smtp-user",
      "Password": "store-this-in-a-secret-provider",
      "UseStartTls": true,
      "DefaultFrom": "noreply@example.com",
      "MaxRetryAttempts": 3
    }
  }
}

public sealed class WelcomeEmailService(IEmailSender emailSender)
{
    public Task SendWelcomeAsync(string to, CancellationToken cancellationToken)
        => emailSender.SendAsync(
            new EmailMessage(to, "Welcome!", "<p>Thanks for joining.</p>"),
            cancellationToken);
}

For a paired HTML and plain-text message, supply PlainTextBody while leaving IsBodyHtml as true:

await emailSender.SendAsync(new EmailMessage(
    "person@example.com",
    "Welcome!",
    "<p>Thanks for joining.</p>",
    PlainTextBody: "Thanks for joining."),
    cancellationToken);

To attach a file and set a Reply-To address, use EmailAttachment and ReplyTo:

await emailSender.SendAsync(new EmailMessage(
    "person@example.com",
    "Your certificate",
    "<p>Attached is your certificate.</p>",
    ReplyTo: "support@example.com",
    Attachments: [new EmailAttachment("certificate.pdf", pdfBytes, "application/pdf")]),
    cancellationToken);

Documentation

• Package guide - public API, sender selection, message semantics, SMTP behavior, retries, cancellation, concurrency, and operational boundaries.
• Runtime SMTP options - static versus database/secret-backed SMTP settings, provider lifecycle, registration order, security, and migration.
• Testing guide - null and in-memory senders, assertions, and advanced transport test seams.
• Agent instructions - repository contracts for AI agents and automated contributors.

Security note

Do not commit SMTP passwords. Use a secret provider or an application-owned ISmtpOptionsProvider, and never log SmtpOptions.Password or decrypted credentials.

Contributing

Keep changes focused, match .editorconfig, update the relevant package and agent documentation, and call out public API or behavior changes in pull requests.

License

MIT - see LICENSE.txt.