Add IMAP support for email fetching and marking as seen

Introduced IMAP functionality to enable fetching emails from an
IMAP server and marking messages as seen. Updated the
`EmailAccountDto` class with IMAP-related properties
(`ImapServer`, `ImapPort`, `ImapUseSsl`) for configuration.

Added `ReceivedEmailContext` to represent received emails and
created the `IImapEmailService` interface with methods
`FetchEmailsAsync` and `MarkAsSeenAsync`. Implemented the
`LimilabsImapEmailService` class using Limilabs Mail.dll for
IMAP operations, including connection handling, email fetching,
and marking messages as seen.

Added `FetchEmailsQuery` and `MarkEmailAsSeenCommand` with
handlers to encapsulate IMAP logic. Updated `EmailsController`
with new endpoints for fetching emails and marking messages as
seen. Registered `IImapEmailService` in `DependencyInjection`.

Included exception handling and logging for robust error
management during IMAP operations.

src/core/DigitalData.MessagingService.Abstraction/EmailAccountDto.cs

@@ -35,4 +35,20 @@ public class EmailAccountDto
     public bool SmtpUseSsl { get; set; }
 
     public bool UseOAuth2 { get; set; }
+
+    /// <summary>
+    /// IMAP server hostname (e.g. "imap.example.com").
+    /// Leave empty when this account is send-only.
+    /// </summary>
+    public string? ImapServer { get; set; }
+
+    /// <summary>
+    /// IMAP server port (993 for SSL, 143 for plain/STARTTLS).
+    /// </summary>
+    public int ImapPort { get; set; } = 993;
+
+    /// <summary>
+    /// Use SSL/TLS when connecting to the IMAP server.
+    /// </summary>
+    public bool ImapUseSsl { get; set; } = true;
 }

src/core/DigitalData.MessagingService.Abstraction/ReceivedEmailContext.cs

@@ -0,0 +1,97 @@
+namespace DigitalData.MessagingService.Abstraction;
+
+/// <summary>
+/// Represents an email message received via IMAP.
+/// </summary>
+public sealed class ReceivedEmailContext
+{
+    /// <summary>
+    /// Unique identifier of the message on the IMAP server (UID).
+    /// </summary>
+#if NET
+    public long Uid { get; init; }
+#else
+    public long Uid { get; set; }
+#endif
+
+    /// <summary>
+    /// Sender address (From header).
+    /// </summary>
+#if NET
+    public string From { get; init; } = string.Empty;
+#else
+    public string From { get; set; } = string.Empty;
+#endif
+
+    /// <summary>
+    /// Recipient addresses (To header).
+    /// </summary>
+#if NET
+    public IEnumerable<string> To { get; init; } = [];
+#else
+    public IEnumerable<string> To { get; set; } = [];
+#endif
+
+    /// <summary>
+    /// CC addresses.
+    /// </summary>
+#if NET
+    public IEnumerable<string> Cc { get; init; } = [];
+#else
+    public IEnumerable<string> Cc { get; set; } = [];
+#endif
+
+    /// <summary>
+    /// Email subject.
+    /// </summary>
+#if NET
+    public string Subject { get; init; } = string.Empty;
+#else
+    public string Subject { get; set; } = string.Empty;
+#endif
+
+    /// <summary>
+    /// Plain-text body (may be empty when only HTML is present).
+    /// </summary>
+#if NET
+    public string TextBody { get; init; } = string.Empty;
+#else
+    public string TextBody { get; set; } = string.Empty;
+#endif
+
+    /// <summary>
+    /// HTML body (may be empty when only plain-text is present).
+    /// </summary>
+#if NET
+    public string HtmlBody { get; init; } = string.Empty;
+#else
+    public string HtmlBody { get; set; } = string.Empty;
+#endif
+
+    /// <summary>
+    /// Date/time the message was sent (Date header).
+    /// </summary>
+#if NET
+    public DateTime Date { get; init; }
+#else
+    public DateTime Date { get; set; }
+#endif
+
+    /// <summary>
+    /// Attachments included with this message.
+    /// </summary>
+#if NET
+    public IEnumerable<EmailAttachmentContext> Attachments { get; init; } = [];
+#else
+    public IEnumerable<EmailAttachmentContext> Attachments { get; set; } = [];
+#endif
+
+    /// <summary>
+    /// Whether the message has been marked as seen/read on the server.
+    /// </summary>
+#if NET
+    public bool IsSeen { get; init; }
+#else
+    public bool IsSeen { get; set; }
+#endif
+}

src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs

@@ -0,0 +1,33 @@
+using DigitalData.MessagingService.Abstraction;
+
+namespace DigitalData.MessagingService.Application.Common.Interfaces;
+
+/// <summary>
+/// Service interface for reading emails via IMAP.
+/// </summary>
+public interface IImapEmailService
+{
+    /// <summary>
+    /// Fetches emails from the specified mailbox folder.
+    /// </summary>
+    /// <param name="account">Account whose IMAP settings will be used.</param>
+    /// <param name="folder">Mailbox folder name (e.g. "INBOX"). Defaults to INBOX.</param>
+    /// <param name="unseenOnly">When <see langword="true"/> returns only unread messages.</param>
+    /// <param name="maxCount">Maximum number of messages to retrieve (most-recent first). 0 = unlimited.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task<IEnumerable<ReceivedEmailContext>> FetchEmailsAsync(
+        EmailAccountDto account,
+        string folder = "INBOX",
+        bool unseenOnly = false,
+        int maxCount = 50,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Marks a message as seen (read) on the server.
+    /// </summary>
+    Task MarkAsSeenAsync(
+        EmailAccountDto account,
+        long uid,
+        string folder = "INBOX",
+        CancellationToken cancellationToken = default);
+}

src/core/DigitalData.MessagingService.Application/EmailReceiving/Commands/MarkEmailAsSeenCommand.cs

@@ -0,0 +1,42 @@
+using DigitalData.MessagingService.Application.Common.Interfaces;
+using DigitalData.MessagingService.Application.EmailAccount.Queries;
+using DigitalData.MessagingService.Domain.Exceptions;
+using MediatR;
+
+namespace DigitalData.MessagingService.Application.EmailReceiving.Commands;
+
+/// <summary>
+/// Command to mark a single IMAP message as seen (read).
+/// </summary>
+public record MarkEmailAsSeenCommand : IRequest
+{
+    public required GetSenderQuery Account { get; init; }
+
+    /// <summary>
+    /// UID of the message to mark as seen.
+    /// </summary>
+    public required long Uid { get; init; }
+
+    /// <summary>
+    /// Mailbox folder the message resides in (default: "INBOX").
+    /// </summary>
+    public string Folder { get; init; } = "INBOX";
+}
+
+public class MarkEmailAsSeenCommandHandler(
+    ISender Sender,
+    IImapEmailService ImapService) : IRequestHandler<MarkEmailAsSeenCommand>
+{
+    public async Task Handle(MarkEmailAsSeenCommand request, CancellationToken cancellationToken)
+    {
+        var account = await Sender.Send(request.Account, cancellationToken)
+            ?? throw new NotFoundException(
+                $"No email account found for the given criteria (Id: {request.Account.Id}, Username: {request.Account.Username}).");
+
+        if (string.IsNullOrWhiteSpace(account.ImapServer))
+            throw new InvalidOperationException(
+                $"IMAP is not configured for account '{account.Username}' (Id: {account.Id}). Set ImapServer in EmailAccounts configuration.");
+
+        await ImapService.MarkAsSeenAsync(account, request.Uid, request.Folder, cancellationToken);
+    }
+}

src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs

@@ -0,0 +1,56 @@
+using DigitalData.MessagingService.Application.Common.Interfaces;
+using DigitalData.MessagingService.Application.EmailAccount.Queries;
+using DigitalData.MessagingService.Abstraction;
+using DigitalData.MessagingService.Domain.Exceptions;
+using MediatR;
+
+namespace DigitalData.MessagingService.Application.EmailReceiving.Queries;
+
+/// <summary>
+/// Query to fetch emails from an IMAP mailbox.
+/// </summary>
+public record FetchEmailsQuery : IRequest<IEnumerable<ReceivedEmailContext>>
+{
+    /// <summary>
+    /// Identifies the email account to use.
+    /// </summary>
+    public required GetSenderQuery Account { get; init; }
+
+    /// <summary>
+    /// Mailbox folder to read from (default: "INBOX").
+    /// </summary>
+    public string Folder { get; init; } = "INBOX";
+
+    /// <summary>
+    /// When <see langword="true"/> returns only unread messages.
+    /// </summary>
+    public bool UnseenOnly { get; init; } = false;
+
+    /// <summary>
+    /// Maximum number of messages to retrieve (most-recent first). 0 = unlimited.
+    /// </summary>
+    public int MaxCount { get; init; } = 50;
+}
+
+public class FetchEmailsQueryHandler(
+    ISender Sender,
+    IImapEmailService ImapService) : IRequestHandler<FetchEmailsQuery, IEnumerable<ReceivedEmailContext>>
+{
+    public async Task<IEnumerable<ReceivedEmailContext>> Handle(FetchEmailsQuery request, CancellationToken cancellationToken)
+    {
+        var account = await Sender.Send(request.Account, cancellationToken)
+            ?? throw new NotFoundException(
+                $"No email account found for the given criteria (Id: {request.Account.Id}, Username: {request.Account.Username}).");
+
+        if (string.IsNullOrWhiteSpace(account.ImapServer))
+            throw new InvalidOperationException(
+                $"IMAP is not configured for account '{account.Username}' (Id: {account.Id}). Set ImapServer in EmailAccounts configuration.");
+
+        return await ImapService.FetchEmailsAsync(
+            account,
+            request.Folder,
+            request.UnseenOnly,
+            request.MaxCount,
+            cancellationToken);
+    }
+}