Improved mailboxes to include sent mails and drafts (#1038)

app/Tests/Settings/MailboxSettingsTests.cs

@@ -42,6 +42,7 @@ public sealed class MailboxSettingsTests
         AuthMethod = MailboxAuthMethod.PASSWORD,
         Username = "someone@example.org",
         RootFolder = "INBOX/Projects",
+        IncludeSentAndDrafts = false,
         MaxAge = MailboxMaxAge.LAST_24_MONTHS,
         IndexAttachments = false,
         MaxAttachmentSizeMegabytes = 25,
@@ -128,6 +129,14 @@ public sealed class MailboxSettingsTests
         });
     }
 
+    [Test]
+    public void AMailboxStoredBeforeSentMailsAndDraftsWereChoosableIncludesThem()
+    {
+        // So the next sync of a mailbox limited to a root folder fetches what it was missing:
+        var mailbox = JsonSerializer.Deserialize<DataSourceMailbox>("""{"RootFolder": "INBOX"}""", SettingsManager.JSON_OPTIONS);
+        Assert.That(mailbox.IncludeSentAndDrafts, Is.True);
+    }
+
     [Test]
     public void ValuesThisVersionCannotReadFallBackToTheSafeSide()
     {

app/Tests/Tools/Mail/MailFolderSelectionTests.cs

@@ -11,12 +11,14 @@ public sealed class MailFolderSelectionTests
     private static readonly IReadOnlyList<MailServerFolder> SERVER_FOLDERS =
     [
         Folder("Archive", MailFolderSpecialUse.ARCHIVE),
+        Folder("Drafts", MailFolderSpecialUse.DRAFTS),
         Folder("Junk", MailFolderSpecialUse.JUNK),
         Folder("Projects"),
         Folder("Projects/Alpha"),
         Folder("Projects/Alpha/Drafts of the board"),
         Folder("ProjectsOld"),
         Folder("Sent", MailFolderSpecialUse.SENT),
+        Folder("Sent/2024"),
         Folder("Starred", MailFolderSpecialUse.FLAGGED),
         Folder("Trash", MailFolderSpecialUse.TRASH),
         Folder("[Gmail]", canSelect: false),
@@ -26,44 +28,84 @@ public sealed class MailFolderSelectionTests
         Folder("INBOX/Invoices"),
     ];
 
+    private static readonly DateTimeOffset RECEIVED_SINCE = new(2025, 10, 10, 0, 0, 0, TimeSpan.Zero);
+
     [Test]
     public void TheWholeMailboxLeavesOutWhatWasThrownAway()
     {
-        var selection = MailFolderSelection.Select(SERVER_FOLDERS, string.Empty);
+        var selection = MailFolderSelection.Select(SERVER_FOLDERS, string.Empty, true);
         Assert.Multiple(() =>
         {
             Assert.That(selection.RootFolderFound, Is.True);
             Assert.That(selection.Folders.Select(folder => folder.FullName), Is.EqualTo(new[]
             {
                 "INBOX",
+                "Sent",
+                "Drafts",
                 "Archive",
                 "INBOX/Invoices",
                 "Projects",
                 "Projects/Alpha",
                 "Projects/Alpha/Drafts of the board",
                 "ProjectsOld",
-                "Sent",
+                "Sent/2024",
                 "[Gmail]/All Mail",
-            }), "The inbox comes first; the trash, the junk folder, the virtual folders and the grouping folder stay out.");
+            }), "The inbox comes first, then the sent mails and the drafts; the trash, the junk folder, the virtual folders and the grouping folder stay out.");
         });
     }
 
+    [Test]
+    public void WithoutTheSentMailsAndDraftsTheWholeMailboxStaysWhole() =>
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, string.Empty, false).Folders, Is.EqualTo(MailFolderSelection.Select(SERVER_FOLDERS, string.Empty, true).Folders), "Without a root folder, the sent mails and the drafts belong to the whole mailbox anyway.");
+
     [Test]
     public void ARootFolderTakesItsSubfoldersAlongAndNothingElse() =>
-        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "Projects").Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Projects", "Projects/Alpha", "Projects/Alpha/Drafts of the board" }), "A folder merely starting with the same name got in.");
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "Projects", false).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Projects", "Projects/Alpha", "Projects/Alpha/Drafts of the board" }), "A folder merely starting with the same name got in.");
+
+    [TestCase(true, new[] { "INBOX", "Sent", "Drafts", "INBOX/Invoices" })]
+    [TestCase(false, new[] { "INBOX", "INBOX/Invoices" })]
+    public void SentMailsAndDraftsComeAlongFromOutsideTheRootFolderWhenIncluded(bool includeSentAndDrafts, string[] expectedFolders) =>
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "INBOX", includeSentAndDrafts).Folders.Select(folder => folder.FullName), Is.EqualTo(expectedFolders), "The subfolders of the sent mails must stay out, since the server marks only the folder itself.");
+
+    [TestCase(true)]
+    [TestCase(false)]
+    public void SentMailsAndDraftsBelowTheRootFolderCountOnce(bool includeSentAndDrafts)
+    {
+        // Some servers keep every folder below the inbox, e.g. Dovecot with the namespace prefix "INBOX.":
+        IReadOnlyList<MailServerFolder> serverFolders =
+        [
+            Folder("INBOX", isInbox: true),
+            Folder("INBOX/Drafts", MailFolderSpecialUse.DRAFTS),
+            Folder("INBOX/Invoices"),
+            Folder("INBOX/Sent", MailFolderSpecialUse.SENT),
+        ];
+
+        Assert.That(MailFolderSelection.Select(serverFolders, "INBOX", includeSentAndDrafts).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "INBOX", "INBOX/Sent", "INBOX/Drafts", "INBOX/Invoices" }));
+    }
+
+    [Test]
+    public void SentMailsAsRootFolderCountOnce() =>
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "Sent", true).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Sent", "Drafts", "Sent/2024" }));
+
+    [Test]
+    public void FoldersTheServerDoesNotMarkAreNeverToldByTheirNames()
+    {
+        IReadOnlyList<MailServerFolder> serverFolders = [Folder("INBOX", isInbox: true), Folder("Drafts"), Folder("Sent")];
+        Assert.That(MailFolderSelection.Select(serverFolders, "INBOX", true).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "INBOX" }), "A server without the special-use marks leaves nothing to tell these folders by.");
+    }
 
     [Test]
     public void TheInboxIsMatchedWhateverItsCase() =>
-        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "inbox").Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "INBOX", "INBOX/Invoices" }));
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "inbox", false).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "INBOX", "INBOX/Invoices" }));
 
     [Test]
     public void AVirtualFolderCountsWhenItIsTheRootFolder() =>
-        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "Starred").Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Starred" }));
+        Assert.That(MailFolderSelection.Select(SERVER_FOLDERS, "Starred", false).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Starred" }));
 
     [Test]
     public void TheTrashNeverCountsNotEvenAsRootFolder()
     {
-        var selection = MailFolderSelection.Select(SERVER_FOLDERS, "Trash");
+        var selection = MailFolderSelection.Select(SERVER_FOLDERS, "Trash", false);
         Assert.Multiple(() =>
         {
             Assert.That(selection.Folders, Is.Empty);
@@ -74,11 +116,11 @@ public sealed class MailFolderSelectionTests
     [Test]
     public void ARootFolderTheServerNoLongerListsIsReported()
     {
-        var selection = MailFolderSelection.Select(SERVER_FOLDERS, "Projects/Beta");
+        var selection = MailFolderSelection.Select(SERVER_FOLDERS, "Projects/Beta", true);
         Assert.Multiple(() =>
         {
-            Assert.That(selection.RootFolderFound, Is.False, "A renamed root folder would read as a mailbox which became empty.");
-            Assert.That(selection.Folders, Is.Empty);
+            Assert.That(selection.RootFolderFound, Is.False, "A renamed root folder would read as a mailbox which became empty, even when the sent mails and the drafts are still there.");
+            Assert.That(selection.Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Sent", "Drafts" }));
         });
     }
 
@@ -86,9 +128,23 @@ public sealed class MailFolderSelectionTests
     public void AServerWithoutHierarchyHasNoSubfolders()
     {
         IReadOnlyList<MailServerFolder> flatFolders = [Folder("Projects", separator: '\0'), Folder("Projects.Alpha", separator: '\0')];
-        Assert.That(MailFolderSelection.Select(flatFolders, "Projects").Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Projects" }));
+        Assert.That(MailFolderSelection.Select(flatFolders, "Projects", true).Folders.Select(folder => folder.FullName), Is.EqualTo(new[] { "Projects" }));
     }
 
+    [TestCase(MailFolderSpecialUse.DRAFTS, false)]
+    [TestCase(MailFolderSpecialUse.SENT, true)]
+    [TestCase(MailFolderSpecialUse.ALL, true)]
+    [TestCase(MailFolderSpecialUse.NONE, true)]
+    public void OnlyDraftsCountWhateverTheirAge(MailFolderSpecialUse specialUse, bool keepsThePeriod)
+    {
+        var expected = keepsThePeriod ? RECEIVED_SINCE : (DateTimeOffset?)null;
+        Assert.That(MailFolderSelection.GetReceivedSince(Folder("Folder", specialUse), RECEIVED_SINCE), Is.EqualTo(expected));
+    }
+
+    [Test]
+    public void AMailboxWithoutPeriodKeepsAllMailsOfEveryFolder() =>
+        Assert.That(MailFolderSelection.GetReceivedSince(Folder("INBOX", isInbox: true), null), Is.Null);
+
     private static MailServerFolder Folder(string fullName, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE, bool isInbox = false, bool canSelect = true, char separator = '/')
     {
         var separatorIndex = separator is '\0' ? -1 : fullName.LastIndexOf(separator);

app/Tests/Tools/Mail/MailboxRetrievalTests.cs

@@ -137,6 +137,21 @@ public sealed class MailboxRetrievalTests
         });
     }
 
+    [Test]
+    public async Task AReadingKnowsWhatTheFoldersOfTheMailboxAreFor()
+    {
+        await this.store.Client.UpsertMailFolderAsync(MAILBOX, new MailFolderRecord("Sent", MailFolderSpecialUse.SENT, 1, null, null, 1, 0, null), TOKEN);
+        var sent = await this.store.StoreMailAsync(MAILBOX, "sent", "Re: Re: Question", "Thanks for your comments.", Mail(new DateTimeOffset(2026, 9, 11, 7, 0, 0, TimeSpan.Zero), new MailLocationRecord("Sent", 1, new MailFlags(true, false, false))));
+
+        var reading = await MailboxRetrievalService.ReadMailAsync(this.store.Client, [WORK], sent, TOKEN);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(reading?.Summary.FolderPaths, Is.EqualTo(new[] { "Sent" }));
+            Assert.That(reading?.MailboxFolders.Select(folder => (folder.Path, folder.SpecialUse)), Is.EquivalentTo(new[] { (INBOX, MailFolderSpecialUse.NONE), ("Sent", MailFolderSpecialUse.SENT) }), "So Read Mail can tell a mail the user sent from one the user received.");
+        });
+    }
+
     [Test]
     public async Task AMailIsReadOnlyFromTheMailboxesGiven()
     {

app/Tests/Tools/ToolCalling/CountMailsToolTests.cs

@@ -86,6 +86,32 @@ public sealed class CountMailsToolTests : ToolRegistryTestBase
         });
     }
 
+    [Test]
+    public void AFolderGroupTellsWhetherItHoldsTheSentMailsOrTheDrafts()
+    {
+        var coverage = new MailboxCoverage(null, null, null, null, [Folder("INBOX", 120, 4), Folder("Sent Items", 40, 0, MailFolderSpecialUse.SENT), Folder("Drafts", 3, 0, MailFolderSpecialUse.DRAFTS)]);
+
+        var sent = CountMailsTool.DescribeGroup(new MailCountGroup("Sent Items", string.Empty, 40), "Sent Items", MailCountGrouping.FOLDER, coverage);
+        var drafts = CountMailsTool.DescribeGroup(new MailCountGroup("Drafts", string.Empty, 3), "Drafts", MailCountGrouping.FOLDER, coverage);
+        var inbox = CountMailsTool.DescribeGroup(new MailCountGroup("INBOX", string.Empty, 12), "INBOX", MailCountGrouping.FOLDER, coverage);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(sent[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]?.GetValue<string>(), Is.EqualTo("sent"));
+            Assert.That(sent["server_message_count"]?.GetValue<long>(), Is.EqualTo(40), "The numbers of the server stay.");
+            Assert.That(drafts[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]?.GetValue<string>(), Is.EqualTo("drafts"));
+            Assert.That(inbox.ContainsKey(MailToolArguments.SPECIAL_FOLDER_ARGUMENT), Is.False);
+        });
+    }
+
+    [Test]
+    public void TheSpecialFolderIsCountedLikeTheSearchFindsIt()
+    {
+        var request = CountMailsTool.ReadRequest(Arguments("""{"special_folder":"sent","to":"alice"}"""), [WORK], TimeZoneInfo.Utc);
+
+        Assert.That(request.Conditions.SpecialFolder, Is.EqualTo(MailFolderSpecialUse.SENT));
+    }
+
     [Test]
     public void TheFunctionOffersExactlyTheMailboxesGiven()
     {
@@ -126,9 +152,9 @@ public sealed class CountMailsToolTests : ToolRegistryTestBase
     }
 
     // Stating its definition and reading its arguments needs none of the services the tool counts with:
-    private CountMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, NullLogger<CountMailsTool>.Instance);
+    private CountMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, null!, NullLogger<CountMailsTool>.Instance);
 
-    private static MailFolderRecord Folder(string path, long? messageCount, long? unseenCount) => new(path, MailFolderSpecialUse.NONE, 1, 100, null, messageCount, unseenCount, null);
+    private static MailFolderRecord Folder(string path, long? messageCount, long? unseenCount, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, 100, null, messageCount, unseenCount, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);
 

app/Tests/Tools/ToolCalling/MailDraftSyncTests.cs

@@ -0,0 +1,121 @@
+using AIStudio.Settings.DataModel;
+using AIStudio.Tools.Databases.IndexStore;
+using AIStudio.Tools.Mail;
+using AIStudio.Tools.Services;
+using AIStudio.Tools.ToolCallingSystem.ToolCallingImplementations.Mailboxes;
+
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace AIStudio.Tests.Tools.ToolCalling;
+
+/// <summary>
+/// Checks when a mail tool syncs a mailbox before it reads the drafts.
+/// </summary>
+/// <remarks>
+/// A user who saved a draft a moment ago and asks the AI to improve it must not hear that there is
+/// no such draft. A sync with every search would go too far, though, and a refused sign-in must never
+/// be tried again on the way, or the account of the user gets locked.
+/// </remarks>
+[TestFixture]
+[NonParallelizable]
+public sealed class MailDraftSyncTests : ToolRegistryTestBase
+{
+    private static readonly DateTimeOffset NOW = new(2026, 10, 10, 9, 0, 0, TimeSpan.Zero);
+
+    private static readonly DataSourceMailbox WORK = new() { Id = "5a1e7c3d-9b2f-4d8e-a6c4-3f0b9d2e1c75", Name = "Work" };
+
+    private static readonly IReadOnlyList<MailFolderRecord> FOLDERS = [Folder("INBOX"), Folder("Entwürfe", MailFolderSpecialUse.DRAFTS), Folder("Gesendet", MailFolderSpecialUse.SENT)];
+
+    [TestCase(true, 120, MailDraftSyncDecision.SYNC_REQUESTED)]
+    [TestCase(true, null, MailDraftSyncDecision.SYNC_REQUESTED)]
+    [TestCase(true, 30, MailDraftSyncDecision.NOT_NEEDED)]
+    [TestCase(false, 120, MailDraftSyncDecision.AUTOMATIC_REFRESH_OFF)]
+    [TestCase(false, 30, MailDraftSyncDecision.NOT_NEEDED)]
+    public void TheDraftsAreSyncedOnlyWhenTheyMayBeOutdated(bool automaticRefresh, int? secondsSinceLastSync, MailDraftSyncDecision expected)
+    {
+        var lastSync = secondsSinceLastSync is { } seconds ? NOW.AddSeconds(-seconds) : (DateTimeOffset?)null;
+
+        Assert.That(MailDraftSync.Decide(true, automaticRefresh, Coverage(lastSync, signInRefusedAtUtc: null), NOW), Is.EqualTo(expected), "A first sync which is still running gets a follow-up, since it may have looked at the drafts before the change.");
+    }
+
+    [Test]
+    public void ReceivedMailsKeepToTheInterval() =>
+        Assert.That(MailDraftSync.Decide(false, true, Coverage(NOW.AddHours(-1), signInRefusedAtUtc: null), NOW), Is.EqualTo(MailDraftSyncDecision.NOT_NEEDED));
+
+    [Test]
+    public void ARefusedSignInIsNeverTriedOnTheWay() =>
+        Assert.That(MailDraftSync.Decide(true, true, Coverage(NOW.AddHours(-1), NOW.AddMinutes(-30)), NOW), Is.EqualTo(MailDraftSyncDecision.NOT_NEEDED), "Every refused attempt brings the account of the user closer to being locked.");
+
+    [Test]
+    public void TheDraftsAreAskedForByTheSpecialFolderOrByTheirPath()
+    {
+        Assert.Multiple(() =>
+        {
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), FOLDERS), Is.True);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), "entwürfe", null), FOLDERS), Is.True, "A model which took the path over from a result asks for the drafts as well.");
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.SENT), FOLDERS), Is.False);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), "INBOX", null), FOLDERS), Is.False);
+            Assert.That(AsksForDrafts(new MailConditions(new MailFilter { IsUnread = true }, null, null), FOLDERS), Is.False, "A search across all folders keeps to the interval.");
+        });
+    }
+
+    [Test]
+    public void AMailboxWithoutAFolderForDraftsMayGetOneWithTheNextSync() =>
+        Assert.That(AsksForDrafts(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), [Folder("INBOX")]), Is.True, "Some servers create the folder only when the first draft is saved.");
+
+    [Test]
+    public async Task ARequestedSyncIsQueued()
+    {
+        this.ConfigureMailbox();
+        using var service = this.CreateService();
+
+        var requested = await service.RequestMailboxSyncAsync(WORK.Id);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(requested, Is.True);
+            Assert.That(service.GetStatuses().Single(status => status.DataSourceId == WORK.Id).State, Is.EqualTo(DataSourceEmbeddingState.QUEUED));
+        });
+    }
+
+    [Test]
+    public async Task WithoutAutomaticRefreshNoSyncIsQueued()
+    {
+        this.ConfigureMailbox();
+        this.SettingsManager.ConfigurationData.App.DataSourceIndexing.AutomaticRefresh = false;
+        using var service = this.CreateService();
+
+        var requested = await service.RequestMailboxSyncAsync(WORK.Id);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(requested, Is.False, "Only the user starts a sync then.");
+            Assert.That(service.GetStatuses(), Is.Empty);
+        });
+    }
+
+    [Test]
+    public async Task AMailboxWhichIsNotConfiguredIsNotSynced()
+    {
+        this.ConfigureMailbox();
+        using var service = this.CreateService();
+
+        Assert.That(await service.RequestMailboxSyncAsync("0e4b8d2a-6c1f-4a9e-b3d7-5f2c8e1a9b64"), Is.False);
+    }
+
+    private static bool AsksForDrafts(MailConditions conditions, IReadOnlyList<MailFolderRecord> folders) => MailDraftSync.AsksForDrafts(conditions, conditions.ForMailbox(folders), folders);
+
+    private static MailboxCoverage Coverage(DateTimeOffset? lastCompleteSyncUtc, DateTimeOffset? signInRefusedAtUtc) => new(null, lastCompleteSyncUtc, signInRefusedAtUtc, null, FOLDERS);
+
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
+
+    private void ConfigureMailbox()
+    {
+        this.SettingsManager.ConfigurationData.Mailboxes.Add(WORK);
+        this.SettingsManager.ConfigurationData.App.EnabledPreviewFeatures.Add(PreviewFeatures.PRE_RAG_2024);
+        this.SettingsManager.ConfigurationData.App.EnabledPreviewFeatures.Add(PreviewFeatures.PRE_MAILBOXES_2026);
+    }
+
+    // Queueing a run needs none of the services which carry it out:
+    private DataSourceEmbeddingService CreateService() => new(this.SettingsManager, null!, null!, null!, NullLogger<DataSourceEmbeddingService>.Instance);
+}

app/Tests/Tools/ToolCalling/MailToolArgumentsTests.cs

@@ -61,7 +61,7 @@ public sealed class MailToolArgumentsTests
     }
 
     [TestCase("""{}""")]
-    [TestCase("""{"from":null,"to":null,"after":null,"before":null,"is_unread":null,"is_flagged":null,"is_encrypted":null,"importance":null,"has_attachments":null,"folder":null}""")]
+    [TestCase("""{"from":null,"to":null,"after":null,"before":null,"is_unread":null,"is_flagged":null,"is_encrypted":null,"importance":null,"has_attachments":null,"folder":null,"special_folder":null}""")]
     public void ConditionsLeftOutHoldForEveryMail(string json)
     {
         var conditions = MailToolArguments.ReadConditions(Arguments(json), UserTimeZone());
@@ -70,9 +70,34 @@ public sealed class MailToolArgumentsTests
         {
             Assert.That(conditions.Filter.HasConditions, Is.False, "A strict schema makes the model pass null for every condition it does not want.");
             Assert.That(conditions.Folder, Is.Null);
+            Assert.That(conditions.SpecialFolder, Is.Null);
+            Assert.That(conditions.NamesFolder, Is.False);
         });
     }
 
+    [TestCase("sent", MailFolderSpecialUse.SENT)]
+    [TestCase("drafts", MailFolderSpecialUse.DRAFTS)]
+    public void ASpecialFolderIsReadAsWhatTheFolderIsFor(string value, MailFolderSpecialUse expected)
+    {
+        var conditions = MailToolArguments.ReadConditions(Arguments($$"""{"special_folder":"{{value}}"}"""), UserTimeZone());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(conditions.SpecialFolder, Is.EqualTo(expected));
+            Assert.That(conditions.Folder, Is.Null);
+            Assert.That(conditions.NamesFolder, Is.True);
+            Assert.That(MailToolArguments.ToArgumentValue(expected), Is.EqualTo(value), "Results mark the mails with the value the argument takes.");
+        });
+    }
+
+    [Test]
+    public void AFolderAndASpecialFolderCannotBeCombined()
+    {
+        var message = Refusal(() => MailToolArguments.ReadConditions(Arguments("""{"folder":"Sent Items","special_folder":"sent"}"""), UserTimeZone()));
+
+        Assert.That(message, Does.Contain("'folder' and 'special_folder' cannot be combined").And.Contain("Leave out 'folder'").And.Contain("or leave out 'special_folder'"), "Two folders would match no mail at all.");
+    }
+
     [TestCase("2026-09-30", "2026-09-01")]
     [TestCase("2026-09-01", "2026-09-01")]
     public void APeriodWhichEndsBeforeItStartsIsRefused(string after, string before)
@@ -88,6 +113,8 @@ public sealed class MailToolArgumentsTests
     [TestCase("""{"after":"last week"}""", "'after' must be a date")]
     [TestCase("""{"from":""}""", "'from' must not be empty")]
     [TestCase("""{"folder":"INBOX\nArchive"}""", "'folder' must not contain control characters")]
+    [TestCase("""{"special_folder":"inbox"}""", "'special_folder' must be one of sent, drafts")]
+    [TestCase("""{"special_folder":"Sent"}""", "'special_folder' must be one of sent, drafts")]
     public void AConditionWhichCannotBeMeantAsWrittenIsRefused(string json, string expectedMessage)
     {
         var message = Refusal(() => MailToolArguments.ReadConditions(Arguments(json), UserTimeZone()));
@@ -121,8 +148,8 @@ public sealed class MailToolArgumentsTests
     {
         var folders = new[] { Folder("INBOX"), Folder("INBOX/Projects"), Folder("Archive"), Folder("archive") };
 
-        var inbox = new MailConditions(new MailFilter(), "Inbox").ForMailbox(folders);
-        var archive = new MailConditions(new MailFilter(), "ARCHIVE").ForMailbox(folders);
+        var inbox = new MailConditions(new MailFilter(), "Inbox", null).ForMailbox(folders);
+        var archive = new MailConditions(new MailFilter(), "ARCHIVE", null).ForMailbox(folders);
 
         Assert.Multiple(() =>
         {
@@ -134,7 +161,7 @@ public sealed class MailToolArgumentsTests
     [Test]
     public void AFolderTheMailboxDoesNotHaveMatchesNoMail()
     {
-        var filter = new MailConditions(new MailFilter { IsUnread = true }, "Projects").ForMailbox([Folder("INBOX")]);
+        var filter = new MailConditions(new MailFilter { IsUnread = true }, "Projects", null).ForMailbox([Folder("INBOX")]);
 
         Assert.Multiple(() =>
         {
@@ -143,10 +170,33 @@ public sealed class MailToolArgumentsTests
         });
     }
 
+    [Test]
+    public void ASpecialFolderIsFoundByWhatTheServerMarksItAsWhateverItsName()
+    {
+        var folders = new[] { Folder("INBOX"), Folder("Gesendete Elemente", MailFolderSpecialUse.SENT), Folder("Sent"), Folder("Entwürfe", MailFolderSpecialUse.DRAFTS) };
+
+        var sent = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.SENT).ForMailbox(folders);
+        var drafts = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS).ForMailbox(folders);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(sent.FolderPaths, Is.EqualTo(new[] { "Gesendete Elemente" }), "A folder merely named like the sent mails is not theirs.");
+            Assert.That(drafts.FolderPaths, Is.EqualTo(new[] { "Entwürfe" }));
+        });
+    }
+
+    [Test]
+    public void ASpecialFolderTheMailboxDoesNotHaveMatchesNoMail()
+    {
+        var filter = new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS).ForMailbox([Folder("INBOX"), Folder("Drafts")]);
+
+        Assert.That(filter.FolderPaths, Is.Empty, "A mailbox which left out its drafts, or whose server does not mark them, must not get the whole mailbox back.");
+    }
+
     [Test]
     public void WithoutAFolderEveryFolderCounts()
     {
-        Assert.That(new MailConditions(new MailFilter(), null).ForMailbox([Folder("INBOX")]).FolderPaths, Is.Null);
+        Assert.That(new MailConditions(new MailFilter(), null, null).ForMailbox([Folder("INBOX")]).FolderPaths, Is.Null);
     }
 
     [Test]
@@ -161,14 +211,15 @@ public sealed class MailToolArgumentsTests
             {
                 MailToolArguments.MAILBOX_IDS_ARGUMENT, MailToolArguments.FROM_ARGUMENT, MailToolArguments.TO_ARGUMENT, MailToolArguments.AFTER_ARGUMENT, MailToolArguments.BEFORE_ARGUMENT,
                 MailToolArguments.IS_UNREAD_ARGUMENT, MailToolArguments.IS_FLAGGED_ARGUMENT, MailToolArguments.IS_ENCRYPTED_ARGUMENT, MailToolArguments.IMPORTANCE_ARGUMENT,
-                MailToolArguments.HAS_ATTACHMENTS_ARGUMENT, MailToolArguments.FOLDER_ARGUMENT,
+                MailToolArguments.HAS_ATTACHMENTS_ARGUMENT, MailToolArguments.FOLDER_ARGUMENT, MailToolArguments.SPECIAL_FOLDER_ARGUMENT,
             }));
+            Assert.That(properties[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]!["enum"]!.AsArray().Select(value => value?.GetValue<string>()), Is.EqualTo(new[] { "sent", "drafts" }));
             Assert.That(properties[MailToolArguments.MAILBOX_IDS_ARGUMENT]!["items"]!["enum"]!.AsArray().Select(id => id!.GetValue<string>()), Is.EqualTo(new[] { WORK.Id, PRIVATE.Id }));
             Assert.That(schema["required"]!.AsArray(), Is.Empty, "Every condition may be left out.");
         });
     }
 
-    private static MailFolderRecord Folder(string path) => new(path, MailFolderSpecialUse.NONE, 1, null, null, null, null, null);
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);
 

app/Tests/Tools/ToolCalling/SearchMailsToolTests.cs

@@ -230,7 +230,7 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
         {
             ReceivedSinceUtc = new DateTimeOffset(2026, 8, 31, 22, 0, 0, TimeSpan.Zero),
             Importance = MailImportance.HIGH,
-        }, "INBOX");
+        }, "INBOX", null);
 
         var description = MailToolResults.DescribeConditions(conditions, timeZone);
 
@@ -243,6 +243,55 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
         });
     }
 
+    [Test]
+    public void TheConditionsShowTheSpecialFolderAsTheArgumentTakesIt()
+    {
+        var description = MailToolResults.DescribeConditions(new MailConditions(new MailFilter(), null, MailFolderSpecialUse.DRAFTS), TimeZoneInfo.Utc);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(description[MailToolArguments.SPECIAL_FOLDER_ARGUMENT]!.GetValue<string>(), Is.EqualTo("drafts"));
+            Assert.That(description.ContainsKey(MailToolArguments.FOLDER_ARGUMENT), Is.False);
+        });
+    }
+
+    [TestCase(new[] { "INBOX" }, null)]
+    [TestCase(new[] { "Sent Items" }, "sent")]
+    [TestCase(new[] { "Drafts" }, "drafts")]
+    [TestCase(new[] { "Drafts", "Sent Items" }, "sent")]
+    [TestCase(new[] { "Elsewhere" }, null)]
+    public void AMailAmongTheSentMailsOrTheDraftsIsMarked(string[] folderPaths, string? expected)
+    {
+        IReadOnlyList<MailFolderRecord> folders = [Folder("INBOX"), Folder("Sent Items", MailFolderSpecialUse.SENT), Folder("Drafts", MailFolderSpecialUse.DRAFTS)];
+
+        Assert.That(MailToolResults.GetSpecialFolder(folderPaths, folders), Is.EqualTo(expected), "A mail in the folder of the sent mails was sent, even when a copy lies among the drafts. A folder the index does not know marks nothing.");
+    }
+
+    [Test]
+    public void AMissingSpecialFolderListsTheFoldersToPickFrom()
+    {
+        var description = new JsonObject();
+        var issues = new JsonArray();
+
+        MailToolResults.DescribeMissingFolder(description, issues, MailFolderSpecialUse.SENT, ["INBOX", "Gesendet"], 2);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(issues.Single()!.GetValue<string>(), Does.Contain("no folder for sent mails").And.Contain("either because the user left it out or because the server does not mark it").And.Contain("pass its path in 'folder' instead of 'special_folder'"));
+            Assert.That(description["folders"]!.AsArray().Select(folder => folder!.GetValue<string>()), Is.EqualTo(new[] { "INBOX", "Gesendet" }));
+        });
+    }
+
+    [Test]
+    public void AMissingFolderByPathOffersNoOtherArgument()
+    {
+        var issues = new JsonArray();
+
+        MailToolResults.DescribeMissingFolder(new JsonObject(), issues, null, ["INBOX", "Archive"], 120);
+
+        Assert.That(issues.Single()!.GetValue<string>(), Does.Contain("no folder with the path given in 'folder'").And.Contain("The first 2 of its 120 folders").And.Not.Contain("special_folder"));
+    }
+
     [Test]
     public void SemanticSearchNeverSeesAMailbox()
     {
@@ -250,7 +299,9 @@ public sealed class SearchMailsToolTests : ToolRegistryTestBase
     }
 
     // Stating its definition and reading its arguments needs none of the services the tool searches with:
-    private SearchMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, NullLogger<SearchMailsTool>.Instance);
+    private SearchMailsTool Tool() => new(this.SettingsManager, new MailboxRetrievalService(this.SettingsManager, null!, null!, NullLogger<MailboxRetrievalService>.Instance), null!, null!, NullLogger<SearchMailsTool>.Instance);
+
+    private static MailFolderRecord Folder(string path, MailFolderSpecialUse specialUse = MailFolderSpecialUse.NONE) => new(path, specialUse, 1, null, null, null, null, null);
 
     private static JsonElement Arguments(string json) => JsonSerializer.Deserialize<JsonElement>(json);