Carneiro.Core.Emails 7.6.2

Carneiro.Core.Emails

A transport-agnostic email sending abstraction (IEmailSender), with an SMTP implementation (SmtpEmailSender) built on MailKit.

Registration

services.AddSmtpEmailSender(configuration);

Overloads also accept an IConfigurationSection, an Action<SmtpEmailSenderOptions>, or a SmtpEmailSenderOptions instance directly. The IConfiguration overload reads from a section named SmtpEmailSenderOptions (nameof(SmtpEmailSenderOptions)).

Registration wires up IEmailSender → SmtpEmailSender (scoped).

IEmailSender

Exposes a single method, SendAsync(EmailMessage message, CancellationToken cancellationToken = default).

Implementations are expected to:

• Use EmailMessage.From when set, otherwise fall back to a sender configured on the implementation itself (e.g. SmtpEmailSenderOptions.DefaultFrom).
• Throw an implementation-specific exception derived from EmailRzException when the message can't be delivered.

SmtpEmailSender

• Connects to the configured SMTP server, optionally authenticates, sends the message, and always disconnects — even on failure.
• Wraps any exception raised while connecting, authenticating, or sending into an EmailSendRzException, logging the failure beforehand.
• Throws InvalidOperationException if the message has no From and no SmtpEmailSenderOptions.DefaultFrom is configured.

SmtpEmailSenderOptions

Settings below are listed by their configuration key, as read from the SmtpEmailSenderOptions section (e.g. an Octopus Deploy structured configuration variable):

• SmtpEmailSenderOptions:Host (string) — the SMTP server host name.
• SmtpEmailSenderOptions:Port (int) — the SMTP server port. Defaults to 587.
• SmtpEmailSenderOptions:SecureSocketOptions (MailKit.Security.SecureSocketOptions) — how the connection is secured. Defaults to StartTlsWhenAvailable.
• SmtpEmailSenderOptions:Username / SmtpEmailSenderOptions:Password (string?) — credentials used to authenticate. When Username is null or empty, no authentication is attempted.
• SmtpEmailSenderOptions:DefaultFrom:Address / SmtpEmailSenderOptions:DefaultFrom:DisplayName (EmailAddress?) — the sender address used when a message doesn't set EmailMessage.From.
• SmtpEmailSenderOptions:Timeout (TimeSpan) — connection and send timeout. Defaults to 30 seconds.

Models

• EmailMessage — From, To, Cc, Bcc, ReplyTo (all EmailAddress), Subject, Body, IsBodyHtml (defaults to true), and Attachments.
• EmailAddress — an Address with an optional DisplayName; implicitly convertible from a plain string, e.g. message.To.Add("jane.doe@example.com").
• EmailAttachment — FileName, Content (byte[]), and ContentType (defaults to application/octet-stream).

Exceptions

• EmailRzException — abstract base for all email-related exceptions.
• EmailSendRzException — thrown by SmtpEmailSender when a message fails to send; wraps the underlying MailKit exception.

Example

var message = new EmailMessage
{
    To = { "jane.doe@example.com" },
    Subject = "Welcome!",
    Body = "<p>Thanks for signing up.</p>",
};

await emailSender.SendAsync(message);