Enhancement: option to stop processing further mail rules (#12053)

src/paperless_mail/mail.py

@@ -575,6 +575,11 @@ class MailAccountHandler(LoggingMixin):
                             rule,
                             supports_gmail_labels=supports_gmail_labels,
                         )
+                        if total_processed_files > 0 and rule.stop_processing:
+                            self.log.debug(
+                                f"Rule {rule}: Stopping processing rules due to stop_processing flag",
+                            )
+                            break
                     except Exception as e:
                         self.log.exception(
                             f"Rule {rule}: Error while processing rule: {e}",

src/paperless_mail/migrations/0002_mailrule_stop_processing.py

@@ -0,0 +1,22 @@
+# Generated by Django 5.1.6 on 2025-02-24 16:07
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("paperless_mail", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="mailrule",
+            name="stop_processing",
+            field=models.BooleanField(
+                default=False,
+                help_text="If True, no further rules will be processed after this one if any document is consumed.",
+                verbose_name="Stop processing further rules",
+            ),
+        ),
+    ]

src/paperless_mail/models.py

@@ -301,6 +301,14 @@ class MailRule(document_models.ModelWithOwner):
         default=True,
     )
 
+    stop_processing = models.BooleanField(
+        _("Stop processing further rules"),
+        default=False,
+        help_text=_(
+            "If True, no further rules will be processed after this one if any document is queued.",
+        ),
+    )
+
     def __str__(self):
         return f"{self.account.name}.{self.name}"
 

src/paperless_mail/serialisers.py

@@ -102,6 +102,7 @@ class MailRuleSerializer(OwnedObjectSerializer):
             "user_can_change",
             "permissions",
             "set_permissions",
+            "stop_processing",
         ]
 
     def update(self, instance, validated_data):

src/paperless_mail/tests/test_mail.py

@@ -1692,6 +1692,39 @@ class TestTasks(TestCase):
         result = tasks.process_mail_accounts(account_ids=[account_b.id])
         self.assertIn("No new", result)
 
+    @mock.patch("paperless_mail.tasks.MailAccountHandler.handle_mail_account")
+    def test_rule_with_stop_processing(self, m):
+        """
+        GIVEN:
+            - Mail account with a rule with stop_processing=True
+        WHEN:
+            - Mail account is processed
+        THEN:
+            - Should only process the first rule
+        """
+        m.side_effect = lambda account: 6
+
+        account = MailAccount.objects.create(
+            name="A",
+            imap_server="A",
+            username="A",
+            password="A",
+        )
+        MailRule.objects.create(
+            name="A",
+            account=account,
+            stop_processing=True,
+        )
+        MailRule.objects.create(
+            name="B",
+            account=account,
+        )
+
+        result = tasks.process_mail_accounts()
+
+        self.assertEqual(m.call_count, 1)
+        self.assertIn("Added 6", result)
+
 
 class TestMailAccountTestView(APITestCase):
     def setUp(self) -> None:
@@ -1777,8 +1810,8 @@ class TestMailAccountTestView(APITestCase):
     )
     def test_mail_account_test_view_refresh_token_fails(
         self,
-        mock_mock_refresh_account_oauth_token,
-    ):
+        mock_mock_refresh_account_oauth_token: mock.MagicMock,
+    ) -> None:
         """
         GIVEN:
             - Mail account with expired token