inital commit

server/app/mailer/sending/imap.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import imaplib
+import re
+import socket
+import ssl
+import time
+from dataclasses import dataclass
+
+from app.mailer.campaign.models import ImapConfig, TransportSecurity
+
+
+class ImapConfigurationError(ValueError):
+    """Raised when IMAP settings are incomplete or inconsistent."""
+
+
+class ImapAppendError(RuntimeError):
+    """Raised when APPENDing to Sent fails.
+
+    temporary=True means retrying later may help. temporary=False means the
+    configuration or mailbox choice probably needs user/admin attention.
+    """
+
+    def __init__(self, message: str, *, temporary: bool | None = None):
+        super().__init__(message)
+        self.temporary = temporary
+
+
+@dataclass(frozen=True, slots=True)
+class ImapAppendResult:
+    host: str
+    port: int
+    security: str
+    folder: str
+    bytes_appended: int
+    response: str | None = None
+
+
+def _require_imap_config(config: ImapConfig) -> tuple[str, int]:
+    if not config.enabled:
+        raise ImapConfigurationError("IMAP is disabled")
+    if not config.host:
+        raise ImapConfigurationError("IMAP host is required")
+    if not config.port:
+        raise ImapConfigurationError("IMAP port is required")
+    if bool(config.username) != bool(config.password):
+        raise ImapConfigurationError("IMAP username and password must be provided together, or both omitted")
+    return config.host, config.port
+
+
+def _open_imap(config: ImapConfig) -> imaplib.IMAP4:
+    host, port = _require_imap_config(config)
+    context = ssl.create_default_context()
+
+    try:
+        if config.security == TransportSecurity.TLS:
+            client: imaplib.IMAP4 = imaplib.IMAP4_SSL(host=host, port=port, timeout=config.timeout_seconds, ssl_context=context)
+        else:
+            client = imaplib.IMAP4(host=host, port=port, timeout=config.timeout_seconds)
+            if config.security == TransportSecurity.STARTTLS:
+                typ, data = client.starttls(ssl_context=context)
+                if typ != "OK":
+                    raise ImapAppendError(f"IMAP STARTTLS failed: {data!r}", temporary=True)
+
+        if config.username and config.password:
+            typ, data = client.login(config.username, config.password)
+            if typ != "OK":
+                raise ImapAppendError(f"IMAP login failed: {data!r}", temporary=False)
+        return client
+    except Exception:
+        try:
+            client.logout()  # type: ignore[possibly-undefined]
+        except Exception:
+            pass
+        raise
+
+
+def _decode_item(item: bytes | str | None) -> str:
+    if item is None:
+        return ""
+    if isinstance(item, bytes):
+        return item.decode("utf-8", errors="replace")
+    return item
+
+
+def _extract_mailbox_name(list_response_line: bytes | str) -> tuple[str, set[str]] | None:
+    """Best-effort parser for IMAP LIST response lines.
+
+    Example lines:
+      (\\HasNoChildren \\Sent) "/" "Sent"
+      (\\HasNoChildren) "/" "Sent Items"
+    """
+
+    line = _decode_item(list_response_line).strip()
+    flags_match = re.match(r"^\((?P<flags>[^)]*)\)\s+", line)
+    flags = set()
+    if flags_match:
+        flags = {part.lower() for part in flags_match.group("flags").split()}
+
+    quoted = re.findall(r'"((?:[^"\\]|\\.)*)"', line)
+    if quoted:
+        # Usually: delimiter, mailbox. Take the last quoted token.
+        return quoted[-1].replace(r'\"', '"'), flags
+
+    # Fallback for unquoted final atom.
+    parts = line.split()
+    if parts:
+        return parts[-1], flags
+    return None
+
+
+def discover_sent_folder(client: imaplib.IMAP4) -> str | None:
+    typ, data = client.list()
+    if typ != "OK" or not data:
+        return None
+
+    parsed: list[tuple[str, set[str]]] = []
+    for item in data:
+        extracted = _extract_mailbox_name(item)
+        if extracted:
+            parsed.append(extracted)
+
+    for name, flags in parsed:
+        if "\\sent" in flags or "\\sentmail" in flags:
+            return name
+
+    common_names = [
+        "Sent",
+        "Sent Items",
+        "Sent Messages",
+        "Gesendet",
+        "Gesendete Elemente",
+        "INBOX.Sent",
+        "INBOX/Sent",
+    ]
+    names = {name.lower(): name for name, _ in parsed}
+    for candidate in common_names:
+        if candidate.lower() in names:
+            return names[candidate.lower()]
+    return None
+
+
+def _effective_sent_folder(*, config: ImapConfig, requested_folder: str | None, client: imaplib.IMAP4) -> str:
+    if requested_folder and requested_folder != "auto":
+        return requested_folder
+    if config.sent_folder and config.sent_folder != "auto":
+        return config.sent_folder
+    discovered = discover_sent_folder(client)
+    if discovered:
+        return discovered
+    raise ImapConfigurationError("Could not discover Sent folder; configure delivery.imap_append_sent.folder or server.imap.sent_folder")
+
+
+def append_message_to_sent(
+    message_bytes: bytes,
+    *,
+    imap_config: ImapConfig,
+    folder: str | None = None,
+) -> ImapAppendResult:
+    """Append a sent MIME message to the configured IMAP Sent folder.
+
+    The SMTP send remains authoritative. APPEND is a separate best-effort step
+    and should not be used to decide whether an email was sent.
+    """
+
+    host, port = _require_imap_config(imap_config)
+    client: imaplib.IMAP4 | None = None
+    try:
+        client = _open_imap(imap_config)
+        target_folder = _effective_sent_folder(config=imap_config, requested_folder=folder, client=client)
+        internal_date = imaplib.Time2Internaldate(time.time())
+        typ, data = client.append(target_folder, "\\Seen", internal_date, message_bytes)
+        if typ != "OK":
+            raise ImapAppendError(f"IMAP APPEND failed for folder {target_folder!r}: {data!r}", temporary=False)
+        response = "; ".join(_decode_item(item) for item in (data or [])) or None
+        return ImapAppendResult(
+            host=host,
+            port=port,
+            security=imap_config.security.value,
+            folder=target_folder,
+            bytes_appended=len(message_bytes),
+            response=response,
+        )
+    except ImapAppendError:
+        raise
+    except (OSError, socket.timeout, imaplib.IMAP4.abort) as exc:
+        raise ImapAppendError(f"IMAP append failed: {exc}", temporary=True) from exc
+    except imaplib.IMAP4.error as exc:
+        raise ImapAppendError(f"IMAP append failed: {exc}", temporary=False) from exc
+    finally:
+        if client is not None:
+            try:
+                client.logout()
+            except Exception:
+                pass