From e840d026aa295f694a479218c5866c75fcaa6ba5 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 11 Aug 2026 15:51:57 +0200
Subject: [PATCH] feat(imap): add markAsSeen option to fetch queries and
 interface

- IImapEmailService.FetchEmailsAsync / FetchEmailByUidAsync now accept
  a bool markAsSeen = true parameter
- FetchEmailsQuery and FetchEmailByUidQuery expose MarkAsSeen { init; } = true
- markAsSeen=true  uses BODY[]      (server sets \\Seen, legacy-compatible)
- markAsSeen=false uses BODY.PEEK[] (non-destructive read, flag untouched)
---
 .../Common/Interfaces/IImapEmailService.cs             | 10 ++++++++++
 .../EmailReceiving/Queries/FetchEmailByUidQuery.cs     |  6 ++++++
 .../EmailReceiving/Queries/FetchEmailsQuery.cs         |  7 +++++++
 3 files changed, 23 insertions(+)

diff --git a/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs b/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs
index 4d4e773..f5a97f1 100644
--- a/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs
+++ b/src/core/DigitalData.MessagingService.Application/Common/Interfaces/IImapEmailService.cs
@@ -13,10 +13,15 @@ public interface IImapEmailService
     /// </summary>
     /// <param name="account">Account whose IMAP settings will be used.</param>
     /// <param name="filter">Filter to apply when fetching emails.</param>
+    /// <param name="markAsSeen">
+    /// When <see langword="true"/> (default), fetched messages are marked as <c>\Seen</c> on the server.
+    /// Set to <see langword="false"/> for a non-destructive read (uses <c>BODY.PEEK</c> internally).
+    /// </param>
     /// <param name="cancellationToken">Cancellation token.</param>
     Task<IEnumerable<ReceivedEmailContext>> FetchEmailsAsync(
         EmailAccountDto account,
         MailSearchFilter filter,
+        bool markAsSeen = true,
         CancellationToken cancellationToken = default);
 
     /// <summary>
@@ -30,11 +35,16 @@ public interface IImapEmailService
     /// <summary>
     /// Fetches a single email by its UID.
     /// </summary>
+    /// <param name="markAsSeen">
+    /// When <see langword="true"/> (default), the message is marked as <c>\Seen</c> on the server.
+    /// Set to <see langword="false"/> for a non-destructive read.
+    /// </param>
     Task<ReceivedEmailContext?> FetchEmailByUidAsync(
         EmailAccountDto account,
         long uid,
         string folder = "INBOX",
         bool withAttachments = false,
+        bool markAsSeen = true,
         CancellationToken cancellationToken = default);
 
     /// <summary>
diff --git a/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailByUidQuery.cs b/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailByUidQuery.cs
index 9597666..37c4fc2 100644
--- a/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailByUidQuery.cs
+++ b/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailByUidQuery.cs
@@ -36,6 +36,11 @@ public record FetchEmailByUidQuery : IRequest<ReceivedEmailContext?>
     /// When <see langword="true"/>, attachment data is included in the result.
     /// </summary>
     public bool WithAttachments { get; init; } = false;
+    /// <summary>
+    /// When <see langword="true"/> (default), the message is marked as <c>\Seen</c> on the server.
+    /// Set to <see langword="false"/> for a non-destructive peek.
+    /// </summary>
+    public bool MarkAsSeen { get; init; } = true;
 }
 
 public class FetchEmailByUidQueryHandler(
@@ -57,6 +62,7 @@ public class FetchEmailByUidQueryHandler(
             (long)request.Uid!,
             request.Folder,
             request.WithAttachments,
+            request.MarkAsSeen,
             cancellationToken);
     }
 }
diff --git a/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs b/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs
index 9b1a6bb..7074d8f 100644
--- a/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs
+++ b/src/core/DigitalData.MessagingService.Application/EmailReceiving/Queries/FetchEmailsQuery.cs
@@ -21,6 +21,12 @@ public record FetchEmailsQuery : IRequest<IEnumerable<ReceivedEmailContext>>
     /// Mail query used to filter and limit the emails retrieved.
     /// </summary>
     public MailSearchFilter Mail { get; init; } = new();
+
+    /// <summary>
+    /// When <see langword="true"/> (default), fetched messages are marked as <c>\Seen</c> on the server.
+    /// Set to <see langword="false"/> for a non-destructive peek.
+    /// </summary>
+    public bool MarkAsSeen { get; init; } = true;
 }
 
 public class FetchEmailsQueryHandler(
@@ -40,6 +46,7 @@ public class FetchEmailsQueryHandler(
         return await ImapService.FetchEmailsAsync(
             account,
             request.Mail,
+            request.MarkAsSeen,
             cancellationToken);
     }
 }