feat: Add configurable sync window (mail.max_sync_days) to limit database growth

appinfo/info.xml

@@ -62,6 +62,7 @@ Learn more about the Nextcloud Ethical AI Rating [in our blog](https://nextcloud
 		<job>OCA\Mail\BackgroundJob\IMipMessageJob</job>
 		<job>OCA\Mail\BackgroundJob\DraftsJob</job>
 		<job>OCA\Mail\BackgroundJob\TrashRetentionJob</job>
+		<job>OCA\Mail\BackgroundJob\SyncWindowCleanupJob</job>
 		<job>OCA\Mail\BackgroundJob\WakeJob</job>
 	</background-jobs>
 	<repair-steps>

appinfo/routes.php

@@ -360,6 +360,11 @@
 			'url' => '/api/settings/layout-message-view',
 			'verb' => 'PUT'
 		],
+		[
+			'name' => 'settings#setMaxSyncDays',
+			'url' => '/api/settings/max-sync-days',
+			'verb' => 'PUT'
+		],
 		[
 			'name' => 'trusted_senders#setTrusted',
 			'url' => '/api/trustedsenders/{email}',

lib/BackgroundJob/BackfillSearchResultsJob.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Mail\BackgroundJob;
+
+use OCA\Mail\Db\MailboxMapper;
+use OCA\Mail\Db\MessageMapper;
+use OCA\Mail\IMAP\IMAPClientFactory;
+use OCA\Mail\IMAP\MessageMapper as ImapMessageMapper;
+use OCA\Mail\Service\AccountService;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\QueuedJob;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Backfills search result messages that exist on IMAP but not in the local DB.
+ *
+ * When a user searches and the IMAP server returns UIDs that are outside the
+ * local sync window, this job fetches their metadata from IMAP and inserts
+ * them into the local DB. The next search will then return complete results.
+ */
+class BackfillSearchResultsJob extends QueuedJob {
+	public function __construct(
+		ITimeFactory $time,
+		private AccountService $accountService,
+		private MailboxMapper $mailboxMapper,
+		private MessageMapper $messageMapper,
+		private IMAPClientFactory $clientFactory,
+		private ImapMessageMapper $imapMapper,
+		private LoggerInterface $logger,
+	) {
+		parent::__construct($time);
+	}
+
+	#[\Override]
+	protected function run($argument): void {
+		$accountId = (int)($argument['accountId'] ?? 0);
+		$mailboxId = (int)($argument['mailboxId'] ?? 0);
+		$uids = $argument['uids'] ?? [];
+
+		if ($accountId === 0 || $mailboxId === 0 || $uids === []) {
+			return;
+		}
+
+		try {
+			$account = $this->accountService->findById($accountId);
+		} catch (DoesNotExistException $e) {
+			return;
+		}
+
+		if (!$account->getMailAccount()->canAuthenticateImap()) {
+			return;
+		}
+
+		try {
+			$mailbox = $this->mailboxMapper->findById($mailboxId);
+		} catch (DoesNotExistException $e) {
+			return;
+		}
+
+		// Re-check which UIDs are still missing (some may have been synced since job was queued)
+		$stillMissing = $this->messageMapper->findMissingUids($mailbox, $uids);
+		if ($stillMissing === []) {
+			$this->logger->debug("BackfillSearchResultsJob: all UIDs already in DB for mailbox $mailboxId");
+			return;
+		}
+
+		// Cap to 200 UIDs per job to limit IMAP load
+		$stillMissing = array_slice($stillMissing, 0, 200);
+
+		$client = $this->clientFactory->getClient($account, false);
+		try {
+			$imapMessages = $this->imapMapper->findByIds(
+				$client,
+				$mailbox->getName(),
+				$stillMissing,
+				$account->getUserId(),
+			);
+
+			if (empty($imapMessages)) {
+				$this->logger->debug("BackfillSearchResultsJob: no messages found on IMAP for mailbox $mailboxId");
+				return;
+			}
+
+			$dbMessages = array_map(
+				static function ($imapMessage) use ($mailbox, $account) {
+					$msg = $imapMessage->toDbMessage($mailbox->getId(), $account->getMailAccount());
+					$msg->setStructureAnalyzed(true);
+					return $msg;
+				},
+				$imapMessages
+			);
+
+			$inserted = $this->messageMapper->insertBulkIgnore($account, ...$dbMessages);
+			$this->logger->debug("BackfillSearchResultsJob: inserted $inserted messages for mailbox $mailboxId");
+		} catch (\Throwable $e) {
+			$this->logger->warning('BackfillSearchResultsJob failed: ' . $e->getMessage(), [
+				'exception' => $e,
+			]);
+		} finally {
+			$client->logout();
+		}
+	}
+}

lib/BackgroundJob/DeepSyncJob.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Mail\BackgroundJob;
+
+use OCA\Mail\Db\MailboxMapper;
+use OCA\Mail\Service\AccountService;
+use OCA\Mail\Service\Sync\ImapToDbSynchronizer;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\QueuedJob;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Background job to deep-sync older messages for a single mailbox.
+ *
+ * This is a QueuedJob (runs once per scheduling) instead of being inlined
+ * in the per-account SyncJob TimedJob. This prevents deep-sync from blocking
+ * the main cron cycle when there are thousands of accounts.
+ *
+ * Nextcloud's cron runner processes QueuedJobs round-robin, so 10K jobs are
+ * spread across multiple cron invocations (~1000 jobs per 5-min cycle).
+ */
+class DeepSyncJob extends QueuedJob {
+	public function __construct(
+		ITimeFactory $time,
+		private AccountService $accountService,
+		private MailboxMapper $mailboxMapper,
+		private ImapToDbSynchronizer $syncService,
+		private LoggerInterface $logger,
+	) {
+		parent::__construct($time);
+	}
+
+	#[\Override]
+	protected function run($argument): void {
+		$accountId = (int)($argument['accountId'] ?? 0);
+		$mailboxId = (int)($argument['mailboxId'] ?? 0);
+
+		if ($accountId === 0 || $mailboxId === 0) {
+			return;
+		}
+
+		try {
+			$account = $this->accountService->findById($accountId);
+		} catch (DoesNotExistException $e) {
+			$this->logger->debug("DeepSyncJob: account $accountId not found, skipping");
+			return;
+		}
+
+		if (!$account->getMailAccount()->canAuthenticateImap()) {
+			return;
+		}
+
+		try {
+			$mailbox = $this->mailboxMapper->findById($mailboxId);
+		} catch (DoesNotExistException $e) {
+			$this->logger->debug("DeepSyncJob: mailbox $mailboxId not found, skipping");
+			return;
+		}
+
+		try {
+			$this->syncService->syncOlderMessagesBackground(
+				$account,
+				$mailbox,
+				$this->logger,
+			);
+		} catch (\Throwable $e) {
+			$this->logger->warning("DeepSyncJob failed for account $accountId mailbox $mailboxId: " . $e->getMessage(), [
+				'exception' => $e,
+			]);
+		}
+	}
+}

lib/BackgroundJob/OnDemandSyncJob.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Mail\BackgroundJob;
+
+use OCA\Mail\Db\MailboxMapper;
+use OCA\Mail\Service\AccountService;
+use OCA\Mail\Service\Sync\ImapToDbSynchronizer;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\QueuedJob;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Async on-demand sync triggered when a user scrolls past cached messages.
+ *
+ * Instead of blocking the HTTP request with a synchronous IMAP fetch,
+ * MailSearch schedules this job. The frontend retries after a short delay
+ * and picks up the newly synced messages from the local DB.
+ */
+class OnDemandSyncJob extends QueuedJob {
+	public function __construct(
+		ITimeFactory $time,
+		private AccountService $accountService,
+		private MailboxMapper $mailboxMapper,
+		private ImapToDbSynchronizer $syncService,
+		private LoggerInterface $logger,
+	) {
+		parent::__construct($time);
+	}
+
+	#[\Override]
+	protected function run($argument): void {
+		$accountId = (int)($argument['accountId'] ?? 0);
+		$mailboxId = (int)($argument['mailboxId'] ?? 0);
+		$cursorTimestamp = (int)($argument['cursorTimestamp'] ?? 0);
+
+		if ($accountId === 0 || $mailboxId === 0 || $cursorTimestamp === 0) {
+			return;
+		}
+
+		try {
+			$account = $this->accountService->findById($accountId);
+		} catch (DoesNotExistException $e) {
+			return;
+		}
+
+		if (!$account->getMailAccount()->canAuthenticateImap()) {
+			return;
+		}
+
+		try {
+			$mailbox = $this->mailboxMapper->findById($mailboxId);
+		} catch (DoesNotExistException $e) {
+			return;
+		}
+
+		try {
+			$synced = $this->syncService->syncOlderMessages(
+				$account,
+				$mailbox,
+				$cursorTimestamp,
+			);
+			$this->logger->debug("OnDemandSyncJob: synced $synced messages for account $accountId mailbox $mailboxId");
+		} catch (\Throwable $e) {
+			$this->logger->warning('OnDemandSyncJob failed: ' . $e->getMessage(), [
+				'exception' => $e,
+			]);
+		}
+	}
+}

lib/BackgroundJob/SyncJob.php

@@ -10,6 +10,7 @@
 
 use Horde_Imap_Client_Exception;
 use OCA\Mail\AppInfo\Application;
+use OCA\Mail\Db\MailboxMapper;
 use OCA\Mail\Exception\IncompleteSyncException;
 use OCA\Mail\Exception\ServiceException;
 use OCA\Mail\IMAP\MailboxSync;
@@ -46,6 +47,7 @@ public function __construct(
 		LoggerInterface $logger,
 		IJobList $jobList,
 		private readonly IConfig $config,
+		private readonly MailboxMapper $mailboxMapper,
 	) {
 		parent::__construct($time);
 
@@ -126,6 +128,25 @@ protected function run($argument) {
 		try {
 			$this->mailboxSync->sync($account, $this->logger, true);
 			$this->syncService->syncAccount($account, $this->logger);
+
+			// Schedule deep-sync as a separate QueuedJob instead of running
+			// it inline. This prevents 10K accounts x 300-800ms from blocking
+			// the entire cron cycle.
+			$maxSyncDays = (int)$this->config->getAppValue('mail', 'max_sync_days', '0');
+			if ($maxSyncDays > 0) {
+				foreach ($this->mailboxMapper->findAll($account) as $mailbox) {
+					if ($mailbox->isInbox()) {
+						$jobArg = [
+							'accountId' => $account->getId(),
+							'mailboxId' => $mailbox->getId(),
+						];
+						if (!$this->jobList->has(DeepSyncJob::class, $jobArg)) {
+							$this->jobList->add(DeepSyncJob::class, $jobArg);
+						}
+						break;
+					}
+				}
+			}
 		} catch (IncompleteSyncException $e) {
 			$this->logger->warning($e->getMessage(), [
 				'exception' => $e,