[Email] Adding categories API

src/System Application/App/Email/src/Connector/EmailConnectorv5.Interface.al

@@ -0,0 +1,36 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace System.Email;
+
+/// <summary>
+/// An e-mail connector interface enhances the "Email Connector v4" with email category management.
+/// </summary>
+interface "Email Connector v5" extends "Email Connector v4"
+{
+    /// <summary>
+    /// Get email categories from the provided account.
+    /// </summary>
+    /// <param name="AccountId">The email account ID.</param>
+    /// <param name="EmailCategories">The email categories retrieved.</param>
+    procedure GetEmailCategories(AccountId: Guid; var EmailCategories: Record "Email Categories" temporary);
+
+    /// <summary>
+    /// Create a new email category in the provided account.
+    /// </summary>
+    /// <param name="AccountId">The email account ID.</param>
+    /// <param name="CategoryDisplayName">The display name of the category to create.</param>
+    /// <param name="CategoryColor">The color of the category (optional).</param>
+    /// <returns>The ID of the created category.</returns>
+    procedure CreateEmailCategory(AccountId: Guid; CategoryDisplayName: Text; CategoryColor: Text): Text;
+
+    /// <summary>
+    /// Apply email categories to an email message.
+    /// </summary>
+    /// <param name="AccountId">The email account ID.</param>
+    /// <param name="ExternalId">The external message ID of the email to update.</param>
+    /// <param name="Categories">The list of category display names to apply to the email.</param>
+    procedure ApplyEmailCategory(AccountId: Guid; ExternalId: Text; Categories: List of [Text]);
+}

src/System Application/App/Email/src/Email/Email.Codeunit.al

@@ -353,6 +353,73 @@ codeunit 8901 Email
 
     #endregion
 
+    #region Categories
+
+    /// <summary>
+    /// Gets email categories from the specified email account.
+    /// </summary>
+    /// <param name="EmailAccountId">The ID of the email account to retrieve categories from.</param>
+    /// <param name="EmailConnector">The email connector to use.</param>
+    /// <param name="EmailCategories">The return record of all categories that were retrieved.</param>
+    procedure GetEmailCategories(EmailAccountId: Guid; EmailConnector: Enum "Email Connector"; var EmailCategories: Record "Email Categories" temporary)
+    begin
+        EmailImpl.GetEmailCategories(EmailAccountId, EmailConnector, EmailCategories);
+    end;
+
+    /// <summary>
+    /// Creates a new email category in the specified email account.
+    /// </summary>
+    /// <param name="EmailAccountId">The ID of the email account to create the category in.</param>
+    /// <param name="EmailConnector">The email connector to use.</param>
+    /// <param name="CategoryDisplayName">The display name of the category to create.</param>
+    /// <returns>The ID of the created category.</returns>
+    procedure CreateEmailCategory(EmailAccountId: Guid; EmailConnector: Enum "Email Connector"; CategoryDisplayName: Text): Text
+    begin
+        exit(EmailImpl.CreateEmailCategory(EmailAccountId, EmailConnector, CategoryDisplayName, ''));
+    end;
+
+    /// <summary>
+    /// Creates a new email category with a specified color in the specified email account.
+    /// </summary>
+    /// <param name="EmailAccountId">The ID of the email account to create the category in.</param>
+    /// <param name="EmailConnector">The email connector to use.</param>
+    /// <param name="CategoryDisplayName">The display name of the category to create.</param>
+    /// <param name="CategoryColor">The color of the category.</param>
+    /// <returns>The ID of the created category.</returns>
+    procedure CreateEmailCategory(EmailAccountId: Guid; EmailConnector: Enum "Email Connector"; CategoryDisplayName: Text; CategoryColor: Text): Text
+    begin
+        exit(EmailImpl.CreateEmailCategory(EmailAccountId, EmailConnector, CategoryDisplayName, CategoryColor));
+    end;
+
+    /// <summary>
+    /// Applies email categories to an email message.
+    /// </summary>
+    /// <param name="EmailAccountId">The ID of the email account containing the email.</param>
+    /// <param name="EmailConnector">The email connector to use.</param>
+    /// <param name="ExternalId">The external message ID of the email to update.</param>
+    /// <param name="CategoryDisplayName">The display name of the category to apply.</param>
+    procedure ApplyEmailCategory(EmailAccountId: Guid; EmailConnector: Enum "Email Connector"; ExternalId: Text; CategoryDisplayName: Text)
+    var
+        Categories: List of [Text];
+    begin
+        Categories.Add(CategoryDisplayName);
+        EmailImpl.ApplyEmailCategory(EmailAccountId, EmailConnector, ExternalId, Categories);
+    end;
+
+    /// <summary>
+    /// Applies email categories to an email message.
+    /// </summary>
+    /// <param name="EmailAccountId">The ID of the email account containing the email.</param>
+    /// <param name="EmailConnector">The email connector to use.</param>
+    /// <param name="ExternalId">The external message ID of the email to update.</param>
+    /// <param name="Categories">The list of category display names to apply to the email.</param>
+    procedure ApplyEmailCategory(EmailAccountId: Guid; EmailConnector: Enum "Email Connector"; ExternalId: Text; Categories: List of [Text])
+    begin
+        EmailImpl.ApplyEmailCategory(EmailAccountId, EmailConnector, ExternalId, Categories);
+    end;
+
+    #endregion
+
     #region OpenInEditor
 
     /// <summary>

src/System Application/App/Email/src/Email/EmailImpl.Codeunit.al

@@ -44,6 +44,7 @@ codeunit 8900 "Email Impl"
         EmailConnectorDoesNotSupportRetrievingEmailsErr: Label 'The selected email connector does not support retrieving emails.';
         EmailConnectorDoesNotSupportMarkAsReadErr: Label 'The selected email connector does not support marking emails as read.';
         EmailconnectorDoesNotSupportReplyingErr: Label 'The selected email connector does not support replying to emails.';
+        EmailConnectorDoesNotSupportCategoriesErr: Label 'The selected email connector does not support email categories.';
         ExternalIdCannotBeEmptyErr: Label 'The external ID cannot be empty.';
         TelemetryRetrieveEmailsUsedTxt: Label 'Retrieving emails is used', Locked = true;
         ErrorCallStackNotFoundErr: Label 'Error call stack not found for the email message with ID %1.', Locked = true;
@@ -270,6 +271,45 @@ codeunit 8900 "Email Impl"
         EmailConnectorv4.GetEmailFolders(EmailAccountId, EmailFolders);
     end;
 
+    procedure GetEmailCategories(EmailAccountId: Guid; Connector: Enum "Email Connector"; var EmailCategories: Record "Email Categories" temporary)
+    var
+        EmailConnectorv5: Interface "Email Connector v5";
+    begin
+        CheckRequiredPermissions();
+
+        if not CheckAndGetEmailConnectorv5(Connector, EmailConnectorv5) then
+            Error(EmailConnectorDoesNotSupportCategoriesErr);
+
+        EmailConnectorv5.GetEmailCategories(EmailAccountId, EmailCategories);
+    end;
+
+    procedure CreateEmailCategory(EmailAccountId: Guid; Connector: Enum "Email Connector"; CategoryDisplayName: Text; CategoryColor: Text): Text
+    var
+        EmailConnectorv5: Interface "Email Connector v5";
+    begin
+        CheckRequiredPermissions();
+
+        if not CheckAndGetEmailConnectorv5(Connector, EmailConnectorv5) then
+            Error(EmailConnectorDoesNotSupportCategoriesErr);
+
+        exit(EmailConnectorv5.CreateEmailCategory(EmailAccountId, CategoryDisplayName, CategoryColor));
+    end;
+
+    procedure ApplyEmailCategory(EmailAccountId: Guid; Connector: Enum "Email Connector"; ExternalId: Text; Categories: List of [Text])
+    var
+        EmailConnectorv5: Interface "Email Connector v5";
+    begin
+        CheckRequiredPermissions();
+
+        if ExternalId = '' then
+            Error(ExternalIdCannotBeEmptyErr);
+
+        if not CheckAndGetEmailConnectorv5(Connector, EmailConnectorv5) then
+            Error(EmailConnectorDoesNotSupportCategoriesErr);
+
+        EmailConnectorv5.ApplyEmailCategory(EmailAccountId, ExternalId, Categories);
+    end;
+
     local procedure TelemetryAppsAndPublishers(Message: Text)
     var
         Telemetry: Codeunit Telemetry;
@@ -393,10 +433,19 @@ codeunit 8900 "Email Impl"
     end;
 #endif
 
-    procedure CheckAndGetEmailConnectorv4(Connector: Interface "Email Connector"; var Connectorv3: Interface "Email Connector v4"): Boolean
+    procedure CheckAndGetEmailConnectorv4(Connector: Interface "Email Connector"; var Connectorv4: Interface "Email Connector v4"): Boolean
     begin
         if Connector is "Email Connector v4" then begin
-            Connectorv3 := Connector as "Email Connector v4";
+            Connectorv4 := Connector as "Email Connector v4";
+            exit(true);
+        end else
+            exit(false);
+    end;
+
+    procedure CheckAndGetEmailConnectorv5(Connector: Interface "Email Connector"; var Connectorv5: Interface "Email Connector v5"): Boolean
+    begin
+        if Connector is "Email Connector v5" then begin
+            Connectorv5 := Connector as "Email Connector v5";
             exit(true);
         end else
             exit(false);

src/System Application/App/Email/src/Email/Inbox/EmailCategories.Table.al

@@ -0,0 +1,53 @@
+// ------------------------------------------------------------------------------------------------
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+// ------------------------------------------------------------------------------------------------
+
+namespace System.Email;
+
+/// <summary>
+/// Holds information about email categories used for tagging emails.
+/// </summary>
+table 8883 "Email Categories"
+{
+    Access = Public;
+    TableType = Temporary;
+    Extensible = false;
+    InherentEntitlements = RIMDX;
+    InherentPermissions = RIMDX;
+
+    fields
+    {
+        field(1; Ordering; Integer)
+        {
+            Caption = 'Ordering';
+            DataClassification = SystemMetadata;
+        }
+        field(2; Id; Text[2048])
+        {
+            Caption = 'Category Id';
+            DataClassification = CustomerContent;
+        }
+        field(3; "Display Name"; Text[2048])
+        {
+            Caption = 'Display Name';
+            DataClassification = CustomerContent;
+        }
+        field(4; Color; Text[50])
+        {
+            Caption = 'Color';
+            DataClassification = CustomerContent;
+        }
+    }
+
+    keys
+    {
+        key(PK; Ordering)
+        {
+            Clustered = true;
+        }
+        key(CategoryId; Id)
+        {
+        }
+    }
+}

src/System Application/App/Email/src/Email/Inbox/EmailRetrievalFilters.Table.al

@@ -61,6 +61,12 @@ table 8885 "Email Retrieval Filters"
             Caption = 'Folder Id';
             DataClassification = CustomerContent;
         }
+        field(10; "Category Filter Type"; Option)
+        {
+            OptionMembers = "Include","Exclude";
+            InitValue = "Include";
+            Caption = 'Category Filter Type';
+        }
     }
 
     keys
@@ -70,4 +76,27 @@ table 8885 "Email Retrieval Filters"
             Clustered = true;
         }
     }
+
+    var
+        CategoryFilters: List of [Text];
+
+    /// <summary>Clears all category filters.</summary>
+    procedure ClearCategoryFilters()
+    begin
+        Clear(CategoryFilters);
+    end;
+
+    /// <summary>Adds a category to the filter list.</summary>
+    /// <param name="Category">The category to add to the filter.</param>
+    procedure AddCategoryFilter(Category: Text)
+    begin
+        CategoryFilters.Add(Category);
+    end;
+
+    /// <summary>Gets the list of category filters.</summary>
+    /// <returns>The list of category filters.</returns>
+    procedure GetCategoryFilters(): List of [Text]
+    begin
+        exit(CategoryFilters);
+    end;
 }