From 962cb52e0b3272bec755c98bb923b461fe11c6bf Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 11 Aug 2026 10:03:22 +0200
Subject: [PATCH] Enhance EmailController with new endpoint and improvements

- Changed HTML body response handling to return Content with
  "text/html" content type for better response clarity.
- Added a new `FetchEmailUids` endpoint to retrieve only email
  UIDs based on query filters, with proper status handling.
- Updated `FetchEmailByUid` to support an optional `htmlBodyOnly`
  parameter, allowing clients to fetch only the HTML body.
- Added XML documentation for new and updated methods.
- Improved response handling and ensured proper HTTP status codes.
---
 .../Controllers/EmailController.cs            | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/presentation/DigitalData.MessagingService.API/Controllers/EmailController.cs b/src/presentation/DigitalData.MessagingService.API/Controllers/EmailController.cs
index c6c9ce3..316bce6 100644
--- a/src/presentation/DigitalData.MessagingService.API/Controllers/EmailController.cs
+++ b/src/presentation/DigitalData.MessagingService.API/Controllers/EmailController.cs
@@ -87,23 +87,44 @@ public class EmailController(IMediator mediator) : ControllerBase
             return NotFound("No emails found matching the specified criteria.");
 
         if (firstHtmlBodyOnly && emails.FirstOrDefault()?.HtmlBody is string htmlBody)
-            return Ok(htmlBody);
+            return Content(htmlBody, "text/html");
 
         return Ok(emails);
     }
 
+    /// <summary>
+    /// Fetch only the UIDs of emails matching the given filter from an IMAP mailbox.
+    /// </summary>
+    /// <param name="query">Query parameters for filtering emails.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>HTTP 200 with the list of matching UIDs, or HTTP 404 if none found.</returns>
+    [HttpGet("uid")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> FetchEmailUids([FromQuery] FetchEmailUidsQuery query, CancellationToken cancellationToken = default)
+    {
+        var uids = await mediator.Send(query, cancellationToken);
+
+        if (!uids.Any())
+            return NotFound("No emails found matching the specified criteria.");
+
+        return Ok(uids);
+    }
+
     /// <summary>
     /// Fetch a single email by its UID from an IMAP mailbox.
     /// </summary>
     /// <param name="uid">The unique identifier (UID) of the message.</param>
     /// <param name="query">Query parameters including account, folder and attachment flag.</param>
+    /// <param name="htmlBodyOnly"></param>
     /// <param name="cancellationToken">Cancellation token.</param>
     /// <returns>HTTP 200 with the matched email, or HTTP 404 if not found.</returns>
     [HttpGet("{uid:long}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> FetchEmailByUid([FromRoute] long uid, [FromQuery] FetchEmailByUidQuery query, CancellationToken cancellationToken = default)
+    public async Task<IActionResult> FetchEmailByUid([FromRoute] long uid, [FromQuery] FetchEmailByUidQuery query, [FromQuery] bool htmlBodyOnly = false, CancellationToken cancellationToken = default)
     {
         var queryWithUid = query.WithUid(uid);
         var email = await mediator.Send(queryWithUid, cancellationToken);
@@ -111,6 +132,9 @@ public class EmailController(IMediator mediator) : ControllerBase
         if (email is null)
             return NotFound($"No email found with UID {uid}.");
 
+        if (htmlBodyOnly)
+            return Content(email.HtmlBody, "text/html");
+
         return Ok(email);
     }