MailToolsBox 1.1.0__tar.gz → 2.0.0__tar.gz

mailtoolsbox-2.0.0/MailToolsBox/__init__.py

@@ -0,0 +1,6 @@
+from MailToolsBox.mailSender import EmailSender, SendAgent
+from MailToolsBox.imapClient import ImapAgent, ImapClient
+
+__version__ = "2.0.0"
+
+__all__ = ["EmailSender", "SendAgent", "ImapClient", "ImapAgent", "__version__"]

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/MailToolsBox/imapClient.py

@@ -1,18 +1,23 @@
 from __future__ import annotations
 
-import imaplib
+import base64
+import datetime as dt
 import email
-import ssl
-import os
+import imaplib
 import json
-import datetime as dt
-import base64
+import logging
+import os
+import re
+import ssl
 from dataclasses import dataclass, field
-from typing import List, Optional, Iterable, Tuple, Dict, Any
-from pathlib import Path
-from enum import Enum
 from email.header import decode_header, make_header
 from email.message import Message
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 
 # ----------------------------- Security -----------------------------
@@ -66,6 +71,15 @@ def _decode_header_value(value: Optional[str]) -> str:
     except Exception:
         return value
 
+
+def _decode_filename(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    try:
+        return str(make_header(decode_header(value)))
+    except Exception:
+        return value
+
 def _parse_addresses(value: Optional[str]) -> List[MailAddress]:
     if not value:
         return []
@@ -79,11 +93,13 @@ def _to_local_datetime(date_hdr: Optional[str]) -> Optional[dt.datetime]:
     if not date_hdr:
         return None
     try:
-        t = email.utils.parsedate_tz(date_hdr)
-        if not t:
+        dt_obj = email.utils.parsedate_to_datetime(date_hdr)
+        if dt_obj is None:
             return None
-        timestamp = email.utils.mktime_tz(t)
-        return dt.datetime.fromtimestamp(timestamp)
+        # Assume UTC when timezone missing to keep comparisons consistent.
+        if dt_obj.tzinfo is None:
+            dt_obj = dt_obj.replace(tzinfo=dt.timezone.utc)
+        return dt_obj
     except Exception:
         return None
 
@@ -232,8 +248,12 @@ class ImapClient:
             # format: b'(\\HasNoChildren) "/" "INBOX/Sub"'
             if not line:
                 continue
-            parts = line.decode("utf-8", errors="ignore").split(" ")
-            name = parts[-1].strip('"')
+            decoded = line.decode("utf-8", errors="ignore")
+            match = re.search(r'"((?:\\.|[^"])*)"$', decoded)
+            if match:
+                name = match.group(1).replace(r"\"", '"')
+            else:
+                name = decoded.split(" ", 1)[-1].strip('"')
             names.append(name)
         return names
 
@@ -293,12 +313,26 @@ class ImapClient:
         text_body: Optional[str] = None
         html_body: Optional[str] = None
         attachments: List[MailPart] = []
+        used_names: Set[str] = set()
 
         if msg.is_multipart():
             for part in msg.walk():
                 ctype = part.get_content_type()
                 dispo = str(part.get("Content-Disposition") or "")
-                filename = part.get_filename()
+                filename_raw = part.get_filename()
+                filename = _decode_filename(filename_raw)
+                if filename:
+                    filename = Path(filename).name
+                    if filename in used_names:
+                        stem = Path(filename).stem
+                        suffix = Path(filename).suffix
+                        counter = 1
+                        candidate = f"{stem}_{counter}{suffix}"
+                        while candidate in used_names:
+                            counter += 1
+                            candidate = f"{stem}_{counter}{suffix}"
+                        filename = candidate
+                    used_names.add(filename)
                 is_attach = "attachment" in dispo.lower() or bool(filename)
                 charset = part.get_content_charset() or "utf-8"
 
@@ -355,7 +389,8 @@ class ImapClient:
         for uid in uids:
             try:
                 out.append(self.fetch(uid))
-            except Exception:
+            except Exception as exc:
+                logger.warning("Failed to fetch UID %s: %s", uid, exc)
                 continue
         return out
 
@@ -499,3 +534,100 @@ class ImapClient:
         self._ensure()
         if not self.selected_mailbox:
             self.select("INBOX")
+
+
+# ----------------------------- Legacy shim -----------------------------
+
+
+class ImapAgent(ImapClient):
+    """
+    Backward compatible adapter that mirrors the old ImapAgent API
+    on top of the modern ImapClient.
+    """
+
+    def __init__(
+        self,
+        email_account: str,
+        password: Optional[str],
+        server_address: str,
+        *,
+        port: int = 993,
+        security_mode: SecurityMode = SecurityMode.SSL,
+        oauth2_access_token: Optional[str] = None,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        allow_invalid_certs: bool = False,
+        timeout: int = 30,
+    ) -> None:
+        super().__init__(
+            email_account=email_account,
+            password=password,
+            server_address=server_address,
+            port=port,
+            security_mode=security_mode,
+            oauth2_access_token=oauth2_access_token,
+            ssl_context=ssl_context,
+            allow_invalid_certs=allow_invalid_certs,
+            timeout=timeout,
+        )
+        self.mail: Optional[imaplib.IMAP4] = None
+
+    def login_account(self) -> imaplib.IMAP4:
+        self.login()
+        self.mail = self.conn
+        return self.mail
+
+    def logout_account(self) -> None:
+        self.logout()
+        self.mail = None
+
+    def __enter__(self) -> "ImapAgent":
+        self.login_account()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.logout_account()
+
+    def _sync_mail_alias(self) -> None:
+        if self.mail and self.conn is None:
+            self.conn = self.mail
+
+    def logout(self) -> None:
+        super().logout()
+        self.mail = None
+
+    def download_mail_text(self, path: str = "", mailbox: str = "INBOX") -> Path:
+        self._sync_mail_alias()
+        return super().download_mail_text(path=path, mailbox=mailbox)
+
+    def download_mail_json(
+        self,
+        lookup: str = "ALL",
+        save: bool = False,
+        path: str = "",
+        file_name: str = "mail.json",
+        mailbox: str = "INBOX",
+    ) -> str:
+        self._sync_mail_alias()
+        return super().download_mail_json(lookup=lookup, save=save, path=path, file_name=file_name, mailbox=mailbox)
+
+    def download_mail_msg(self, path: str = "", lookup: str = "ALL", mailbox: str = "INBOX") -> List[Path]:
+        """
+        Save each selected message as a .msg file (wrapper over .eml bytes).
+        """
+        self._sync_mail_alias()
+        self.login()
+        try:
+            self.select(mailbox)
+            uids = self.search(lookup)
+            out_paths: List[Path] = []
+            target_dir = Path(path or ".")
+            target_dir.mkdir(parents=True, exist_ok=True)
+            for i, uid in enumerate(uids):
+                item = self.fetch(uid)
+                file_name = f"email_{i}.msg"
+                out = target_dir / file_name
+                out.write_bytes(item.raw)
+                out_paths.append(out)
+            return out_paths
+        finally:
+            self.logout()

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/MailToolsBox/mailSender.py

@@ -20,7 +20,7 @@ import mimetypes
 
 from enum import Enum
 from pathlib import Path
-from typing import List, Optional, Iterable, Tuple
+from typing import Iterable, List, Optional, Tuple
 
 from email.mime.text import MIMEText
 from email.mime.multipart import MIMEMultipart
@@ -28,7 +28,6 @@ from email.mime.application import MIMEApplication
 from email.mime.base import MIMEBase
 from email import encoders
 from email.utils import formatdate
-from email_validator import validate_email, EmailNotValidError
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 
 # ---------------------------------------------------------------------
@@ -38,6 +37,22 @@ logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
 
+# ---------------------------------------------------------------------
+# Optional imports
+# ---------------------------------------------------------------------
+def _load_email_validator():
+    """Import email-validator only when validation is requested."""
+    try:
+        from email_validator import validate_email, EmailNotValidError  # type: ignore
+    except Exception as exc:  # ImportError or runtime import issues
+        raise ImportError(
+            "Email validation requested but the optional dependency `email-validator` "
+            "is not installed. Install it with `pip install \"MailToolsBox[validation]\"` "
+            "or set validate_emails=False."
+        ) from exc
+    return validate_email, EmailNotValidError
+
+
 # ---------------------------------------------------------------------
 # Security modes
 # ---------------------------------------------------------------------
@@ -75,7 +90,7 @@ class EmailSender:
         *,
         port: int = 587,
         timeout: int = 30,
-        validate_emails: bool = True,
+        validate_emails: bool = False,
         template_dir: Optional[str] = None,
         security_mode: SecurityMode = SecurityMode.AUTO,
         oauth2_access_token: Optional[str] = None,
@@ -117,6 +132,16 @@ class EmailSender:
             self.user_email, self.server_smtp_address, self.port, self.security_mode
         )
 
+    def _resolve_security_mode(
+        self,
+        security_mode: Optional[SecurityMode],
+        use_tls: Optional[bool],
+    ) -> SecurityMode:
+        mode = SecurityMode(security_mode) if security_mode else self.security_mode
+        if use_tls is not None:
+            mode = SecurityMode.STARTTLS if use_tls else SecurityMode.NONE
+        return mode
+
     # ----------------- Convenience constructors -----------------
 
     @classmethod
@@ -176,10 +201,11 @@ class EmailSender:
 
     def _validate_email(self, email_address: str) -> str:
         """Validate and normalize email address using email-validator."""
+        validate_email, email_error = _load_email_validator()
         try:
             result = validate_email(email_address, check_deliverability=False)
             return result.normalized
-        except EmailNotValidError as e:
+        except email_error as e:
             logger.error("Invalid email address: %s", email_address)
             raise ValueError(f"Invalid email address: {email_address}") from e
 
@@ -309,9 +335,9 @@ class EmailSender:
 
     # ----------------- Connection helpers -----------------
 
-    def _open_sync(self) -> smtplib.SMTP:
+    def _open_sync(self, mode: Optional[SecurityMode] = None) -> smtplib.SMTP:
         """Open a synchronous SMTP connection with requested security behavior."""
-        mode = self.security_mode
+        mode = mode or self.security_mode
         if mode == SecurityMode.AUTO and self.port == 465:
             mode = SecurityMode.SSL
 
@@ -340,29 +366,19 @@ class EmailSender:
         # mode NONE means keep plain
         return server
 
-    def _aiosmtp(self) -> aiosmtplib.SMTP:
+    def _aiosmtp(self, mode: SecurityMode) -> aiosmtplib.SMTP:
         """Create an aiosmtplib.SMTP instance with proper TLS flags."""
-        mode = self.security_mode
         if mode == SecurityMode.AUTO and self.port == 465:
             mode = SecurityMode.SSL
 
         use_tls = mode == SecurityMode.SSL
-        if mode == SecurityMode.STARTTLS:
-            start_tls = True
-        elif mode == SecurityMode.NONE:
-            start_tls = False
-        elif mode == SecurityMode.SSL:
-            start_tls = False  # implicit TLS already
-        else:
-            start_tls = None  # auto upgrade if server advertises STARTTLS
-
         # Note: no duplicated parameters here
         return aiosmtplib.SMTP(
             hostname=self.server_smtp_address,
             port=self.port,
             timeout=self.timeout,
             use_tls=use_tls,
-            start_tls=start_tls,
+            start_tls=False,  # handle STARTTLS manually after connect
             tls_context=self.ssl_context,
         )
 
@@ -410,6 +426,7 @@ class EmailSender:
         attachments: Optional[Iterable[str]] = None,
         html: bool = False,
         security_mode: Optional[SecurityMode] = None,
+        use_tls: Optional[bool] = None,
     ) -> None:
         """Send a single message synchronously."""
         recipients_list = list(recipients)
@@ -426,13 +443,9 @@ class EmailSender:
         if attachments:
             self._add_attachments(msg, attachments)
 
-        # Temporarily override security if provided at call site
-        original_mode = self.security_mode
-        if security_mode:
-            self.security_mode = SecurityMode(security_mode)
-
+        mode = self._resolve_security_mode(security_mode, use_tls)
         try:
-            with self._open_sync() as server:
+            with self._open_sync(mode) as server:
                 self._smtp_login_sync(server)
                 all_recipients = list(validated_to)
                 if validated_cc:
@@ -446,8 +459,6 @@ class EmailSender:
         except Exception as e:
             logger.error("Unexpected error: %s", str(e))
             raise
-        finally:
-            self.security_mode = original_mode
 
     def send_bulk(
         self,
@@ -478,6 +489,7 @@ class EmailSender:
         bcc: Optional[Iterable[str]] = None,
         attachments: Optional[Iterable[str]] = None,
         security_mode: Optional[SecurityMode] = None,
+        use_tls: Optional[bool] = None,
     ) -> None:
         """Render a Jinja2 template and send as HTML."""
         template = self.template_env.get_template(template_name)
@@ -491,6 +503,7 @@ class EmailSender:
             attachments=attachments,
             html=True,
             security_mode=security_mode,
+            use_tls=use_tls,
         )
 
     # ----------------- Public API: async -----------------
@@ -506,6 +519,7 @@ class EmailSender:
         attachments: Optional[Iterable[str]] = None,
         html: bool = False,
         security_mode: Optional[SecurityMode] = None,
+        use_tls: Optional[bool] = None,
     ) -> None:
         """Send a single message asynchronously using aiosmtplib."""
         recipients_list = list(recipients)
@@ -522,14 +536,20 @@ class EmailSender:
         if attachments:
             await self._add_attachments_async(msg, attachments)
 
-        original_mode = self.security_mode
-        if security_mode:
-            self.security_mode = SecurityMode(security_mode)
+        mode = self._resolve_security_mode(security_mode, use_tls)
 
         try:
-            server = self._aiosmtp()
+            server = self._aiosmtp(mode)
             await server.connect()
             try:
+                if mode == SecurityMode.STARTTLS or (
+                    mode == SecurityMode.AUTO and server.supports_extension("starttls")
+                ):
+                    await server.starttls(context=self.ssl_context)
+                    if self.ehlo_hostname:
+                        await server.ehlo(self.ehlo_hostname)
+                    else:
+                        await server.ehlo()
                 await self._smtp_login_async(server)
                 all_recipients = list(validated_to)
                 if validated_cc:
@@ -545,8 +565,6 @@ class EmailSender:
         except Exception as e:
             logger.error("Unexpected error: %s", str(e))
             raise
-        finally:
-            self.security_mode = original_mode
 
     async def send_bulk_async(
         self,

mailtoolsbox-2.0.0/MailToolsBox/templates/example.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<body>
+<h1>{{ subject or "Hello" }}</h1>
+<p>{{ body or "This is a sample template shipped with MailToolsBox." }}</p>
+</body>
+</html>

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/MailToolsBox.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: MailToolsBox
-Version: 1.1.0
+Version: 2.0.0
 Summary: Modern sync and async SMTP with optional TLS/SSL, OAuth2 XOAUTH2, Jinja2 templates, and attachments.
 Home-page: https://github.com/rambod/MailToolsBox
-Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.1.0.tar.gz
+Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v2.0.0.tar.gz
 Author: Rambod Ghashghai
 Author-email: gh.rambod@gmail.com
 License: MIT
@@ -26,15 +26,20 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: Jinja2>=3.0.2
-Requires-Dist: email-validator>=2.0.0
 Requires-Dist: aiosmtplib>=2.0.0
 Requires-Dist: aiofiles>=23.0.0
+Provides-Extra: validation
+Requires-Dist: email-validator>=2.0.0; extra == "validation"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: email-validator>=2.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.20; extra == "test"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -70,7 +75,7 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 - Jinja2 templates with auto plain text fallback
 - MIME smart attachment handling
 - Bulk sending helpers
-- Email validation
+- Optional email validation (opt-in extra)
 - Environment variable configuration
 - Backward compatibility shim `SendAgent`
 
@@ -80,6 +85,9 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 
 ```bash
 pip install MailToolsBox
+
+# Optional: include address validation support
+pip install "MailToolsBox[validation]"
 ```
 
 ---
@@ -97,6 +105,8 @@ sender = EmailSender(
     user_email_password="password",
     port=587,                        # typical for STARTTLS
     security_mode="starttls"         # or "auto"
+    # validation is off by default to keep dependencies light;
+    # enable with validate_emails=True after installing the [validation] extra
 )
 
 sender.send(
@@ -109,7 +119,7 @@ sender.send(
 ### Read emails
 
 ```python
-from MailToolsBox.imap_client import ImapClient  # or the path you placed it under
+from MailToolsBox import ImapClient
 
 with ImapClient(
     email_account="you@example.com",
@@ -140,6 +150,8 @@ with ImapClient(
 - `ssl`: implicit SSL on connect, typical for port 465.
 - `none`: no TLS. Use only inside trusted networks.
 
+You can also pass `use_tls=True` to force STARTTLS regardless of the configured `security_mode` (or `use_tls=False` to force plaintext for trusted relays).
+
 ### Gmail and Exchange recipes
 
 ```python
@@ -150,6 +162,17 @@ sender.send(["to@example.com"], "Hi", "Body")
 # Exchange Online with SMTP AUTH
 exchange = EmailSender.for_exchange_smtp_auth("you@company.com", "password")
 exchange.send(["person@company.com"], "Status", "Body")
+
+# Exchange on-prem with self-signed certs (only on trusted networks)
+exchange_on_prem = EmailSender(
+    user_email="you@corp.local",
+    server_smtp_address="mail.corp.local",
+    user_email_password="password",
+    port=587,
+    security_mode="starttls",
+    allow_invalid_certs=True,  # accept self-signed certs on trusted networks
+)
+exchange_on_prem.send(["admin@corp.local"], "Status", "Body")
 ```
 
 ### OAuth2 XOAUTH2
@@ -232,7 +255,8 @@ imap = ImapClient(
     password="password",
     server_address="imap.example.com",
     port=993,
-    security_mode="ssl"
+    security_mode="ssl",
+    allow_invalid_certs=False,  # set True to accept self-signed certs
 )
 imap.login()
 imap.select("INBOX")
@@ -256,6 +280,8 @@ export IMAP_PORT=993
 export IMAP_SECURITY=ssl
 # Optional OAuth token
 export IMAP_OAUTH2_TOKEN=ya29.a0Af...
+# Accept self-signed certs for dev/on-prem only
+export IMAP_ALLOW_INVALID_CERTS=1
 ```
 
 ### Search and fetch
@@ -317,7 +343,7 @@ with imap:
 
 ## Validation and templates
 
-- Addresses are normalized with `email-validator` when validation is enabled.
+- Addresses are normalized with `email-validator` only when you opt in via `validate_emails=True` and install the optional extra: `pip install "MailToolsBox[validation]"`.
 - Templates use Jinja2 with autoescape for HTML and XML.
 - HTML sending includes a plain text alternative for better deliverability.
 
@@ -358,17 +384,32 @@ legacy = SendAgent("you@example.com", "smtp.example.com", "pw", port=587)
 legacy.send_mail(["to@example.com"], "Subject", "Body", tls=True)
 ```
 
+`ImapAgent` remains as a thin adapter over `ImapClient` for projects that still import the legacy name.
+
 ---
 
 ## Security notes
 
 - Prefer `ssl` on 465 or `starttls` on 587.
+- To accept self-signed certificates for SMTP/IMAP on trusted networks, pass `allow_invalid_certs=True`.
+- To intentionally skip TLS (inside trusted networks only), use `security_mode="none"`.
+- For on-prem Exchange or legacy servers with self-signed certificates, pass `allow_invalid_certs=True` (SMTP/IMAP) only on trusted networks.
 - Use app passwords when your provider offers them.
 - Prefer OAuth2 tokens for long term services.
 - Use `none` only on trusted networks.
 
 ---
 
+## Testing
+
+```bash
+pip install -e ".[dev]"        # or: pip install -r requirements-dev.txt
+pytest
+```
+Tests are network-free and rely on local fakes, so they run quickly.
+
+---
+
 ## Troubleshooting
 
 - Authentication errors on Gmail usually mean you need an app password or OAuth2.

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/MailToolsBox.egg-info/SOURCES.txt

@@ -9,5 +9,6 @@ MailToolsBox.egg-info/SOURCES.txt
 MailToolsBox.egg-info/dependency_links.txt
 MailToolsBox.egg-info/requires.txt
 MailToolsBox.egg-info/top_level.txt
+MailToolsBox/templates/example.html
 tests/test_imap_agent.py
 tests/test_mail_sender.py

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/MailToolsBox.egg-info/requires.txt

@@ -1,5 +1,4 @@
 Jinja2>=3.0.2
-email-validator>=2.0.0
 aiosmtplib>=2.0.0
 aiofiles>=23.0.0
 
@@ -9,7 +8,15 @@ pytest-asyncio>=0.20
 mypy>=1.0
 black>=24.0
 ruff>=0.5
+email-validator>=2.0.0
 
 [docs]
 mkdocs>=1.5
 mkdocs-material>=9.5
+
+[test]
+pytest>=7.0
+pytest-asyncio>=0.20
+
+[validation]
+email-validator>=2.0.0

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: MailToolsBox
-Version: 1.1.0
+Version: 2.0.0
 Summary: Modern sync and async SMTP with optional TLS/SSL, OAuth2 XOAUTH2, Jinja2 templates, and attachments.
 Home-page: https://github.com/rambod/MailToolsBox
-Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.1.0.tar.gz
+Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v2.0.0.tar.gz
 Author: Rambod Ghashghai
 Author-email: gh.rambod@gmail.com
 License: MIT
@@ -26,15 +26,20 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: Jinja2>=3.0.2
-Requires-Dist: email-validator>=2.0.0
 Requires-Dist: aiosmtplib>=2.0.0
 Requires-Dist: aiofiles>=23.0.0
+Provides-Extra: validation
+Requires-Dist: email-validator>=2.0.0; extra == "validation"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: email-validator>=2.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.20; extra == "test"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -70,7 +75,7 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 - Jinja2 templates with auto plain text fallback
 - MIME smart attachment handling
 - Bulk sending helpers
-- Email validation
+- Optional email validation (opt-in extra)
 - Environment variable configuration
 - Backward compatibility shim `SendAgent`
 
@@ -80,6 +85,9 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 
 ```bash
 pip install MailToolsBox
+
+# Optional: include address validation support
+pip install "MailToolsBox[validation]"
 ```
 
 ---
@@ -97,6 +105,8 @@ sender = EmailSender(
     user_email_password="password",
     port=587,                        # typical for STARTTLS
     security_mode="starttls"         # or "auto"
+    # validation is off by default to keep dependencies light;
+    # enable with validate_emails=True after installing the [validation] extra
 )
 
 sender.send(
@@ -109,7 +119,7 @@ sender.send(
 ### Read emails
 
 ```python
-from MailToolsBox.imap_client import ImapClient  # or the path you placed it under
+from MailToolsBox import ImapClient
 
 with ImapClient(
     email_account="you@example.com",
@@ -140,6 +150,8 @@ with ImapClient(
 - `ssl`: implicit SSL on connect, typical for port 465.
 - `none`: no TLS. Use only inside trusted networks.
 
+You can also pass `use_tls=True` to force STARTTLS regardless of the configured `security_mode` (or `use_tls=False` to force plaintext for trusted relays).
+
 ### Gmail and Exchange recipes
 
 ```python
@@ -150,6 +162,17 @@ sender.send(["to@example.com"], "Hi", "Body")
 # Exchange Online with SMTP AUTH
 exchange = EmailSender.for_exchange_smtp_auth("you@company.com", "password")
 exchange.send(["person@company.com"], "Status", "Body")
+
+# Exchange on-prem with self-signed certs (only on trusted networks)
+exchange_on_prem = EmailSender(
+    user_email="you@corp.local",
+    server_smtp_address="mail.corp.local",
+    user_email_password="password",
+    port=587,
+    security_mode="starttls",
+    allow_invalid_certs=True,  # accept self-signed certs on trusted networks
+)
+exchange_on_prem.send(["admin@corp.local"], "Status", "Body")
 ```
 
 ### OAuth2 XOAUTH2
@@ -232,7 +255,8 @@ imap = ImapClient(
     password="password",
     server_address="imap.example.com",
     port=993,
-    security_mode="ssl"
+    security_mode="ssl",
+    allow_invalid_certs=False,  # set True to accept self-signed certs
 )
 imap.login()
 imap.select("INBOX")
@@ -256,6 +280,8 @@ export IMAP_PORT=993
 export IMAP_SECURITY=ssl
 # Optional OAuth token
 export IMAP_OAUTH2_TOKEN=ya29.a0Af...
+# Accept self-signed certs for dev/on-prem only
+export IMAP_ALLOW_INVALID_CERTS=1
 ```
 
 ### Search and fetch
@@ -317,7 +343,7 @@ with imap:
 
 ## Validation and templates
 
-- Addresses are normalized with `email-validator` when validation is enabled.
+- Addresses are normalized with `email-validator` only when you opt in via `validate_emails=True` and install the optional extra: `pip install "MailToolsBox[validation]"`.
 - Templates use Jinja2 with autoescape for HTML and XML.
 - HTML sending includes a plain text alternative for better deliverability.
 
@@ -358,17 +384,32 @@ legacy = SendAgent("you@example.com", "smtp.example.com", "pw", port=587)
 legacy.send_mail(["to@example.com"], "Subject", "Body", tls=True)
 ```
 
+`ImapAgent` remains as a thin adapter over `ImapClient` for projects that still import the legacy name.
+
 ---
 
 ## Security notes
 
 - Prefer `ssl` on 465 or `starttls` on 587.
+- To accept self-signed certificates for SMTP/IMAP on trusted networks, pass `allow_invalid_certs=True`.
+- To intentionally skip TLS (inside trusted networks only), use `security_mode="none"`.
+- For on-prem Exchange or legacy servers with self-signed certificates, pass `allow_invalid_certs=True` (SMTP/IMAP) only on trusted networks.
 - Use app passwords when your provider offers them.
 - Prefer OAuth2 tokens for long term services.
 - Use `none` only on trusted networks.
 
 ---
 
+## Testing
+
+```bash
+pip install -e ".[dev]"        # or: pip install -r requirements-dev.txt
+pytest
+```
+Tests are network-free and rely on local fakes, so they run quickly.
+
+---
+
 ## Troubleshooting
 
 - Authentication errors on Gmail usually mean you need an app password or OAuth2.

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/README.md

@@ -14,7 +14,7 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 - Jinja2 templates with auto plain text fallback
 - MIME smart attachment handling
 - Bulk sending helpers
-- Email validation
+- Optional email validation (opt-in extra)
 - Environment variable configuration
 - Backward compatibility shim `SendAgent`
 
@@ -24,6 +24,9 @@ MailToolsBox is a modern, pragmatic email toolkit for Python. It gives you clean
 
 ```bash
 pip install MailToolsBox
+
+# Optional: include address validation support
+pip install "MailToolsBox[validation]"
 ```
 
 ---
@@ -41,6 +44,8 @@ sender = EmailSender(
     user_email_password="password",
     port=587,                        # typical for STARTTLS
     security_mode="starttls"         # or "auto"
+    # validation is off by default to keep dependencies light;
+    # enable with validate_emails=True after installing the [validation] extra
 )
 
 sender.send(
@@ -53,7 +58,7 @@ sender.send(
 ### Read emails
 
 ```python
-from MailToolsBox.imap_client import ImapClient  # or the path you placed it under
+from MailToolsBox import ImapClient
 
 with ImapClient(
     email_account="you@example.com",
@@ -84,6 +89,8 @@ with ImapClient(
 - `ssl`: implicit SSL on connect, typical for port 465.
 - `none`: no TLS. Use only inside trusted networks.
 
+You can also pass `use_tls=True` to force STARTTLS regardless of the configured `security_mode` (or `use_tls=False` to force plaintext for trusted relays).
+
 ### Gmail and Exchange recipes
 
 ```python
@@ -94,6 +101,17 @@ sender.send(["to@example.com"], "Hi", "Body")
 # Exchange Online with SMTP AUTH
 exchange = EmailSender.for_exchange_smtp_auth("you@company.com", "password")
 exchange.send(["person@company.com"], "Status", "Body")
+
+# Exchange on-prem with self-signed certs (only on trusted networks)
+exchange_on_prem = EmailSender(
+    user_email="you@corp.local",
+    server_smtp_address="mail.corp.local",
+    user_email_password="password",
+    port=587,
+    security_mode="starttls",
+    allow_invalid_certs=True,  # accept self-signed certs on trusted networks
+)
+exchange_on_prem.send(["admin@corp.local"], "Status", "Body")
 ```
 
 ### OAuth2 XOAUTH2
@@ -176,7 +194,8 @@ imap = ImapClient(
     password="password",
     server_address="imap.example.com",
     port=993,
-    security_mode="ssl"
+    security_mode="ssl",
+    allow_invalid_certs=False,  # set True to accept self-signed certs
 )
 imap.login()
 imap.select("INBOX")
@@ -200,6 +219,8 @@ export IMAP_PORT=993
 export IMAP_SECURITY=ssl
 # Optional OAuth token
 export IMAP_OAUTH2_TOKEN=ya29.a0Af...
+# Accept self-signed certs for dev/on-prem only
+export IMAP_ALLOW_INVALID_CERTS=1
 ```
 
 ### Search and fetch
@@ -261,7 +282,7 @@ with imap:
 
 ## Validation and templates
 
-- Addresses are normalized with `email-validator` when validation is enabled.
+- Addresses are normalized with `email-validator` only when you opt in via `validate_emails=True` and install the optional extra: `pip install "MailToolsBox[validation]"`.
 - Templates use Jinja2 with autoescape for HTML and XML.
 - HTML sending includes a plain text alternative for better deliverability.
 
@@ -302,17 +323,32 @@ legacy = SendAgent("you@example.com", "smtp.example.com", "pw", port=587)
 legacy.send_mail(["to@example.com"], "Subject", "Body", tls=True)
 ```
 
+`ImapAgent` remains as a thin adapter over `ImapClient` for projects that still import the legacy name.
+
 ---
 
 ## Security notes
 
 - Prefer `ssl` on 465 or `starttls` on 587.
+- To accept self-signed certificates for SMTP/IMAP on trusted networks, pass `allow_invalid_certs=True`.
+- To intentionally skip TLS (inside trusted networks only), use `security_mode="none"`.
+- For on-prem Exchange or legacy servers with self-signed certificates, pass `allow_invalid_certs=True` (SMTP/IMAP) only on trusted networks.
 - Use app passwords when your provider offers them.
 - Prefer OAuth2 tokens for long term services.
 - Use `none` only on trusted networks.
 
 ---
 
+## Testing
+
+```bash
+pip install -e ".[dev]"        # or: pip install -r requirements-dev.txt
+pytest
+```
+Tests are network-free and rely on local fakes, so they run quickly.
+
+---
+
 ## Troubleshooting
 
 - Authentication errors on Gmail usually mean you need an app password or OAuth2.

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/setup.py

@@ -6,7 +6,7 @@ README = (ROOT / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="MailToolsBox",
-    version="1.1.0",
+    version="2.0.0",
     description="Modern sync and async SMTP with optional TLS/SSL, OAuth2 XOAUTH2, Jinja2 templates, and attachments.",
     long_description=README,
     long_description_content_type="text/markdown",
@@ -14,7 +14,7 @@ setup(
     author="Rambod Ghashghai",
     author_email="gh.rambod@gmail.com",
     url="https://github.com/rambod/MailToolsBox",
-    download_url="https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.1.0.tar.gz",
+    download_url="https://github.com/rambod/MailToolsBox/archive/refs/tags/v2.0.0.tar.gz",
     packages=find_packages(exclude=("tests", "examples")),
     include_package_data=True,  # needed with package_data to ship templates
     package_data={
@@ -23,17 +23,24 @@ setup(
     },
     install_requires=[
         "Jinja2>=3.0.2",
-        "email-validator>=2.0.0",
         "aiosmtplib>=2.0.0",
         "aiofiles>=23.0.0",
     ],
     extras_require={
+        "validation": [
+            "email-validator>=2.0.0",
+        ],
         "dev": [
             "pytest>=7.0",
             "pytest-asyncio>=0.20",
             "mypy>=1.0",
             "black>=24.0",
             "ruff>=0.5",
+            "email-validator>=2.0.0",
+        ],
+        "test": [
+            "pytest>=7.0",
+            "pytest-asyncio>=0.20",
         ],
         "docs": [
             "mkdocs>=1.5",

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/tests/test_imap_agent.py

@@ -5,6 +5,7 @@ from unittest import mock
 import os
 import types
 import sys
+import ssl
 
 import pytest
 
@@ -27,15 +28,8 @@ sys.modules.setdefault(
         select_autoescape=lambda x: None,
     ),
 )
-sys.modules.setdefault(
-    "email_validator",
-    types.SimpleNamespace(
-        validate_email=lambda email, check_deliverability=False: types.SimpleNamespace(normalized=email),
-        EmailNotValidError=Exception,
-    ),
-)
 
-from MailToolsBox.imapClient import ImapAgent
+from MailToolsBox.imapClient import ImapAgent, SecurityMode
 
 
 class DummyMail:
@@ -46,7 +40,8 @@ class DummyMail:
         self.selected = None
     def login(self, user, password):
         self.logged_in = True
-    def select(self, mailbox):
+        return ("OK", [b""])
+    def select(self, mailbox, readonly=True):
         self.selected = mailbox
         return ('OK', [b''])
     def uid(self, command, *args):
@@ -75,7 +70,7 @@ def sample_message_bytes():
 
 def test_login_account(monkeypatch):
     dummy = DummyMail(sample_message_bytes())
-    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda addr: dummy)
+    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda *args, **kwargs: dummy)
     agent = ImapAgent('user', 'pass', 'imap.example.com')
     agent.login_account()
     assert agent.mail is dummy
@@ -104,7 +99,7 @@ def test_download_mail_json(tmp_path, monkeypatch, trailing):
     message_bytes = sample_message_bytes()
     dummy = DummyMail(message_bytes)
     monkeypatch.setattr(ImapAgent, 'login_account', lambda self: None)
-    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda addr: dummy)
+    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda *args, **kwargs: dummy)
 
     agent = ImapAgent('user', 'pass', 'imap.example.com')
     path = str(tmp_path) + (os.sep if trailing else "")
@@ -124,10 +119,16 @@ def test_download_mail_msg(tmp_path, trailing):
     dummy = DummyMail(message_bytes)
     agent = ImapAgent('user', 'pass', 'imap.example.com')
     agent.login_account = lambda: setattr(agent, 'mail', dummy)
+    # avoid real network in _open
+    import imaplib as _imaplib
+    _orig_ssl = _imaplib.IMAP4_SSL
+    _imaplib.IMAP4_SSL = lambda *a, **k: dummy
 
     path = str(tmp_path) + (os.sep if trailing else "")
     agent.download_mail_msg(path=path)
 
+    _imaplib.IMAP4_SSL = _orig_ssl
+
     file_path = tmp_path / 'email_0.msg'
     assert file_path.exists()
 
@@ -146,7 +147,7 @@ def test_from_env(monkeypatch):
 
 def test_context_manager(monkeypatch):
     dummy = DummyMail(sample_message_bytes())
-    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda addr: dummy)
+    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda *args, **kwargs: dummy)
 
     with ImapAgent('user', 'pass', 'imap.example.com') as agent:
         assert agent.mail is dummy
@@ -155,3 +156,30 @@ def test_context_manager(monkeypatch):
     assert agent.mail is None
 
 
+def test_imap_allow_invalid_certs_sets_context():
+    client = ImapAgent("user@example.com", "pw", "imap.example.com", allow_invalid_certs=True)
+    assert client.ssl_context.check_hostname is False
+    assert client.ssl_context.verify_mode == ssl.CERT_NONE
+
+
+def test_imap_plain_connection(monkeypatch):
+    class PlainIMAP:
+        def __init__(self, *args, **kwargs):
+            self.started_tls = False
+            self.timeout = None
+
+        def starttls(self, ctx):
+            self.started_tls = True
+
+    monkeypatch.setattr('imaplib.IMAP4', PlainIMAP)
+
+    client = ImapAgent(
+        "user@example.com",
+        "pw",
+        "imap.example.com",
+        port=143,
+        security_mode=SecurityMode.NONE,
+    )
+    conn = client._open()
+    assert isinstance(conn, PlainIMAP)
+    assert not getattr(conn, "started_tls", False)

{mailtoolsbox-1.1.0 → mailtoolsbox-2.0.0}/tests/test_mail_sender.py

@@ -6,6 +6,7 @@ import sys
 from pathlib import Path
 from email.mime.multipart import MIMEMultipart
 import time
+import ssl
 import pytest
 
 # Provide dummy aiosmtplib to satisfy imports
@@ -27,13 +28,6 @@ sys.modules.setdefault(
         select_autoescape=lambda x: None,
     ),
 )
-sys.modules.setdefault(
-    "email_validator",
-    types.SimpleNamespace(
-        validate_email=lambda email, check_deliverability=False: types.SimpleNamespace(normalized=email),
-        EmailNotValidError=Exception,
-    ),
-)
 
 from MailToolsBox.mailSender import EmailSender
 
@@ -62,7 +56,7 @@ def test_email_sender_send(monkeypatch):
         use_tls=True,
     )
 
-    smtp_class.assert_called_with("smtp.example.com", 25, timeout=10)
+    smtp_class.assert_called_with("smtp.example.com", 25, timeout=30)
     smtp_instance.starttls.assert_called()
     smtp_instance.login.assert_called_with("user@example.com", "pass")
     smtp_instance.send_message.assert_called()
@@ -210,12 +204,90 @@ def test_send_template_custom_directory(monkeypatch):
     assert captured["body"] == "rendered"
 
 
+def test_email_validation_is_lazy(monkeypatch):
+    from MailToolsBox import mailSender as ms
+
+    called = {"loader": False}
+
+    def blow_up():
+        called["loader"] = True
+        raise ImportError("no validator")
+
+    monkeypatch.setattr(ms, "_load_email_validator", blow_up)
+
+    smtp_instance = mock.MagicMock()
+    smtp_instance.__enter__.return_value = smtp_instance
+    smtp_instance.__exit__.return_value = None
+    smtp_class = mock.MagicMock(return_value=smtp_instance)
+    monkeypatch.setattr(smtplib, "SMTP", smtp_class)
+
+    sender = EmailSender(
+        user_email="user@example.com",
+        server_smtp_address="smtp.example.com",
+        user_email_password="pass",
+        validate_emails=False,  # default path should not import validator
+    )
+
+    sender.send(recipients=["to@example.com"], subject="Subj", message_body="Body")
+
+    assert called["loader"] is False
+    smtp_instance.send_message.assert_called()
+
+
+def test_email_validation_requires_optional_dependency(monkeypatch):
+    from MailToolsBox import mailSender as ms
+
+    def blow_up():
+        raise ImportError("no validator")
+
+    monkeypatch.setattr(ms, "_load_email_validator", blow_up)
+
+    with pytest.raises(ImportError):
+        EmailSender(
+            user_email="user@example.com",
+            server_smtp_address="smtp.example.com",
+            validate_emails=True,
+        )
+
+
+def test_email_validation_normalizes(monkeypatch):
+    from MailToolsBox import mailSender as ms
+
+    def loader():
+        def validator(addr, check_deliverability=False):
+            return types.SimpleNamespace(normalized=addr.lower())
+
+        return validator, ValueError
+
+    monkeypatch.setattr(ms, "_load_email_validator", loader)
+
+    sender = EmailSender(
+        user_email="USER@Example.COM",
+        server_smtp_address="smtp.example.com",
+        validate_emails=True,
+    )
+
+    assert sender.user_email == "user@example.com"
+
+
+def test_allow_invalid_certs_sets_context():
+    sender = EmailSender(
+        user_email="user@example.com",
+        server_smtp_address="smtp.example.com",
+        allow_invalid_certs=True,
+    )
+
+    assert sender.ssl_context.check_hostname is False
+    assert sender.ssl_context.verify_mode == ssl.CERT_NONE
+
+
 class DummyAsyncSMTP:
     def __init__(self):
         self.started_tls = False
         self.logged_in = None
         self.sent_message = None
         self.to_addrs = None
+        self.extensions = {"starttls"}
 
     async def __aenter__(self):
         return self
@@ -223,9 +295,18 @@ class DummyAsyncSMTP:
     async def __aexit__(self, exc_type, exc, tb):
         pass
 
+    async def connect(self):
+        return None
+
     async def starttls(self, context=None):
         self.started_tls = True
 
+    def supports_extension(self, ext):
+        return ext.lower() in self.extensions
+
+    async def ehlo(self, hostname=None):
+        return None
+
     async def login(self, user, password):
         self.logged_in = (user, password)
 
@@ -233,6 +314,9 @@ class DummyAsyncSMTP:
         self.sent_message = msg
         self.to_addrs = to_addrs
 
+    async def quit(self):
+        return None
+
 
 def test_send_async_uses_async_attachment(monkeypatch):
     smtp_instance = DummyAsyncSMTP()
@@ -426,5 +510,3 @@ def test_send_bulk_async_concurrent(monkeypatch):
     )
 
     assert start["b@example.com"] < end["a@example.com"]
-
-

mailtoolsbox-1.1.0/MailToolsBox/__init__.py

@@ -1,6 +0,0 @@
-from MailToolsBox.mailSender import EmailSender, SendAgent
-from MailToolsBox.imapClient import ImapAgent
-
-__version__ = "1.0.1"
-
-__all__ = ["EmailSender", "SendAgent", "ImapAgent", "__version__"]