feat: respect BACKEND_MUTATE to avoid mutating backend mailboxes by default; add tests and docs

proxy_server.py

@@ -51,6 +51,10 @@ class Settings:
     BACKEND_SMTP_PASS = os.getenv("BACKEND_SMTP_PASS")
     BACKEND_SMTP_USE_SSL = env_bool("BACKEND_SMTP_USE_SSL", True)
     BACKEND_SMTP_USE_TLS = env_bool("BACKEND_SMTP_USE_TLS", False)
+    # When false (default) the proxy will not mutate backend mailboxes
+    # (no STORE +FLAGS / EXPUNGE). Set to true only when deletions should
+    # be propagated to the backend IMAP server.
+    BACKEND_MUTATE = env_bool("BACKEND_MUTATE", False)
 
     @classmethod
     def validate(cls):
@@ -376,9 +380,12 @@ class POP3Session:
 
     async def handle_quit(self):
         if self._imap:
-            for uid in self.deleted:
-                await asyncio.to_thread(self._imap.mark_deleted, uid)
-            await asyncio.to_thread(self._imap.expunge)
+            # Only propagate deletes to the backend when explicitly enabled.
+            if Settings.BACKEND_MUTATE:
+                for uid in self.deleted:
+                    await asyncio.to_thread(self._imap.mark_deleted, uid)
+                await asyncio.to_thread(self._imap.expunge)
+            # Always logout the backend connection.
             self._imap.logout()
         await self.send_line("+OK Goodbye")