merge: SquidStd.Mail SMTP sender (IMailSender, OutgoingMailMessage, send events)

Author: tgiachi

src/SquidStd.Mail.Abstractions/Data/Config/SmtpOptions.cs

@@ -0,0 +1,25 @@
+using SquidStd.Mail.Abstractions.Data;
+
+namespace SquidStd.Mail.Abstractions.Data.Config;
+
+/// <summary>Plain options for the SMTP sender (passed directly to AddMailSender).</summary>
+public sealed class SmtpOptions
+{
+    /// <summary>SMTP server host.</summary>
+    public string Host { get; set; } = string.Empty;
+
+    /// <summary>SMTP server port.</summary>
+    public int Port { get; set; } = 587;
+
+    /// <summary>Use SSL-on-connect (<c>true</c>) or STARTTLS-when-available (<c>false</c>).</summary>
+    public bool UseSsl { get; set; }
+
+    /// <summary>Login user name; when empty, authentication is skipped.</summary>
+    public string Username { get; set; } = string.Empty;
+
+    /// <summary>Login password.</summary>
+    public string Password { get; set; } = string.Empty;
+
+    /// <summary>Default sender used when a message has no <c>From</c>.</summary>
+    public MailAddress? DefaultFrom { get; set; }
+}

src/SquidStd.Mail.Abstractions/Data/Events/MailSendFailedEvent.cs

@@ -0,0 +1,10 @@
+using SquidStd.Core.Interfaces.Events;
+using SquidStd.Mail.Abstractions.Data;
+
+namespace SquidStd.Mail.Abstractions.Data.Events;
+
+/// <summary>Published when sending a message fails.</summary>
+/// <param name="To">Primary recipients.</param>
+/// <param name="Subject">Message subject.</param>
+/// <param name="Error">Failure reason.</param>
+public sealed record MailSendFailedEvent(IReadOnlyList<MailAddress> To, string Subject, string Error) : IEvent;

src/SquidStd.Mail.Abstractions/Data/Events/MailSentEvent.cs

@@ -0,0 +1,9 @@
+using SquidStd.Core.Interfaces.Events;
+using SquidStd.Mail.Abstractions.Data;
+
+namespace SquidStd.Mail.Abstractions.Data.Events;
+
+/// <summary>Published after a message is sent successfully.</summary>
+/// <param name="To">Primary recipients.</param>
+/// <param name="Subject">Message subject.</param>
+public sealed record MailSentEvent(IReadOnlyList<MailAddress> To, string Subject) : IEvent;

src/SquidStd.Mail.Abstractions/Data/OutgoingAttachment.cs

@@ -0,0 +1,7 @@
+namespace SquidStd.Mail.Abstractions.Data;
+
+/// <summary>An attachment to send with an outgoing message.</summary>
+/// <param name="FileName">Attachment file name.</param>
+/// <param name="ContentType">MIME content type, e.g. <c>application/pdf</c>.</param>
+/// <param name="Content">Raw bytes.</param>
+public sealed record OutgoingAttachment(string FileName, string ContentType, byte[] Content);

src/SquidStd.Mail.Abstractions/Data/OutgoingMailMessage.cs

@@ -0,0 +1,29 @@
+namespace SquidStd.Mail.Abstractions.Data;
+
+/// <summary>An email to send. Build with an object initializer.</summary>
+public sealed record OutgoingMailMessage
+{
+    /// <summary>Sender; falls back to <c>SmtpOptions.DefaultFrom</c> when null.</summary>
+    public MailAddress? From { get; init; }
+
+    /// <summary>Primary recipients (required, non-empty).</summary>
+    public IReadOnlyList<MailAddress> To { get; init; } = [];
+
+    /// <summary>Carbon-copy recipients.</summary>
+    public IReadOnlyList<MailAddress> Cc { get; init; } = [];
+
+    /// <summary>Blind carbon-copy recipients.</summary>
+    public IReadOnlyList<MailAddress> Bcc { get; init; } = [];
+
+    /// <summary>Subject line.</summary>
+    public string Subject { get; init; } = string.Empty;
+
+    /// <summary>Plain-text body, or null.</summary>
+    public string? TextBody { get; init; }
+
+    /// <summary>HTML body, or null.</summary>
+    public string? HtmlBody { get; init; }
+
+    /// <summary>Attachments.</summary>
+    public IReadOnlyList<OutgoingAttachment> Attachments { get; init; } = [];
+}

src/SquidStd.Mail.Abstractions/Exceptions/MailSendException.cs

@@ -0,0 +1,11 @@
+namespace SquidStd.Mail.Abstractions.Exceptions;
+
+/// <summary>Thrown when an outbound message cannot be sent.</summary>
+public sealed class MailSendException : Exception
+{
+    /// <summary>Initializes the exception with a message and the underlying cause.</summary>
+    public MailSendException(string message, Exception innerException)
+        : base(message, innerException)
+    {
+    }
+}

src/SquidStd.Mail.Abstractions/Interfaces/IMailSender.cs

@@ -0,0 +1,10 @@
+using SquidStd.Mail.Abstractions.Data;
+
+namespace SquidStd.Mail.Abstractions.Interfaces;
+
+/// <summary>Sends outbound email.</summary>
+public interface IMailSender
+{
+    /// <summary>Sends a message; throws <see cref="Exceptions.MailSendException" /> on failure.</summary>
+    Task SendAsync(OutgoingMailMessage message, CancellationToken cancellationToken = default);
+}

src/SquidStd.Mail.Abstractions/README.md

@@ -28,6 +28,10 @@ dotnet add package SquidStd.Mail.Abstractions
 | `MailReceivedEvent` | Published on the event bus per new message. |
 | `IMailReader` | Fetches new messages from a mailbox. |
 | `MailOptions` | Host/port/credentials, protocol, polling and fetch options. |
+| `IMailSender` | Sends outbound email. |
+| `OutgoingMailMessage` | An email to send (recipients, subject, bodies, attachments). |
+| `SmtpOptions` | SMTP host/port/SSL/credentials and a default sender. |
+| `MailSentEvent` / `MailSendFailedEvent` | Published on the event bus on send success/failure. |
 
 ## License
 

src/SquidStd.Mail.MailKit/Extensions/MailSenderRegistrationExtensions.cs

@@ -0,0 +1,28 @@
+using DryIoc;
+using SquidStd.Mail.Abstractions.Data.Config;
+using SquidStd.Mail.Abstractions.Interfaces;
+using SquidStd.Mail.MailKit.Services;
+
+namespace SquidStd.Mail.MailKit.Extensions;
+
+/// <summary>DryIoc registration helper for the SMTP sender.</summary>
+public static class MailSenderRegistrationExtensions
+{
+    /// <summary>Registers <see cref="SmtpOptions" /> and <see cref="IMailSender" /> (MailKit SMTP).</summary>
+    public static IContainer AddMailSender(this IContainer container, SmtpOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(container);
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentException.ThrowIfNullOrWhiteSpace(options.Host);
+
+        if (options.Port <= 0)
+        {
+            throw new ArgumentException("Port must be positive.", nameof(options));
+        }
+
+        container.RegisterInstance(options);
+        container.Register<IMailSender, MailKitMailSender>(Reuse.Singleton);
+
+        return container;
+    }
+}

src/SquidStd.Mail.MailKit/README.md

@@ -44,6 +44,36 @@ container.AddMail(new MailOptions
 Listen with an `IAsyncEventListener<MailReceivedEvent>` registered on the `IEventBus`. IMAP marks messages
 `\Seen` after fetch (configurable); POP3 dedups by UIDL and can delete after download.
 
+## Sending (SMTP)
+
+```csharp
+using DryIoc;
+using SquidStd.Mail.Abstractions.Data;
+using SquidStd.Mail.Abstractions.Data.Config;
+using SquidStd.Mail.Abstractions.Interfaces;
+using SquidStd.Mail.MailKit.Extensions;
+
+container.AddMailSender(new SmtpOptions
+{
+    Host = "smtp.example.com",
+    Port = 587,
+    UseSsl = false,
+    Username = "user@example.com",
+    Password = "secret",
+    DefaultFrom = new MailAddress("App", "app@example.com")
+});
+
+var sender = container.Resolve<IMailSender>();
+await sender.SendAsync(new OutgoingMailMessage
+{
+    To = [new MailAddress("Bob", "bob@example.com")],
+    Subject = "Welcome",
+    HtmlBody = "<p>Hello!</p>"
+});
+```
+
+`MailSentEvent` / `MailSendFailedEvent` are published on the `IEventBus`; failures throw `MailSendException`.
+
 ## License
 
 MIT — part of [SquidStd](https://github.com/tgiachi/squid-std).