MailToolsBox 1.0.0__tar.gz → 1.0.1__tar.gz

mailtoolsbox-1.0.1/MailToolsBox/__init__.py

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

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox/imapClient.py

@@ -2,6 +2,7 @@ import imaplib
 import email
 import json
 import datetime
+import os
 from typing import List
 
 
@@ -12,11 +13,46 @@ class ImapAgent:
         self.server_address = server_address
         self.mail = None
 
+    @classmethod
+    def from_env(cls) -> "ImapAgent":
+        """Create :class:`ImapAgent` from environment variables.
+
+        Required variables are ``IMAP_EMAIL``, ``IMAP_PASSWORD`` and
+        ``IMAP_SERVER``.
+        """
+        email_account = os.environ["IMAP_EMAIL"]
+        password = os.environ["IMAP_PASSWORD"]
+        server = os.environ["IMAP_SERVER"]
+        return cls(email_account, password, server)
+
+    def __enter__(self) -> "ImapAgent":
+        self.login_account()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.logout_account()
+
     def login_account(self):
         self.mail = imaplib.IMAP4_SSL(self.server_address)
         self.mail.login(self.email_account, self.password)
 
+    def logout_account(self):
+        if self.mail is not None:
+            try:
+                self.mail.logout()
+            finally:
+                self.mail = None
+
     def download_mail_text(self, path='', mailbox='INBOX'):
+        """Download all emails in ``mailbox`` and write them as plain text.
+
+        This method now ensures that a connection to the IMAP server has been
+        established before attempting to access any mailbox.  If no connection
+        exists, :py:meth:`login_account` is invoked to create one.
+        """
+        if self.mail is None:
+            self.login_account()
+
         with open(f'{path}email.txt', 'w') as f:
             self.mail.select(mailbox)
             _, data = self.mail.uid('search', None, 'ALL')
@@ -48,15 +84,14 @@ class ImapAgent:
                         f.write(
                             f"From: {email_from}\nTo: {email_to}\nDate: {local_message_date}\nSubject: {subject}\n\nBody:\n\n{body.decode('utf-8')}\n\n")
         self.mail.close()
+        self.logout_account()
 
-    import json
 
     def download_mail_json(self, lookup: str = 'ALL', save: bool = False, path: str = '', file_name: str = 'mail.json') -> str:
         save_json = save
-        self.login_account()
 
-        with imaplib.IMAP4_SSL(self.imap_server) as mail:
-            mail.login(self.username, self.password)
+        with imaplib.IMAP4_SSL(self.server_address) as mail:
+            mail.login(self.email_account, self.password)
             mail.select("inbox")
             result, data = mail.uid('search', None, lookup)  # (ALL/UNSEEN)
             uids = data[0].split()
@@ -117,3 +152,5 @@ class ImapAgent:
             file_name = f"{path}email_{i}.msg"
             with open(file_name, 'w') as f:
                 f.write(email_message.as_string())
+        self.mail.close()
+        self.logout_account()

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox/mailSender.py

@@ -1,18 +1,20 @@
+import os
 import smtplib
+import aiosmtplib
 from email.mime.text import MIMEText
 from email.mime.multipart import MIMEMultipart
 from email.mime.application import MIMEApplication
 from email.utils import COMMASPACE, formatdate
-from jinja2 import Template, Environment, FileSystemLoader, select_autoescape
+from jinja2 import Environment, FileSystemLoader, select_autoescape
 from typing import List, Optional, Iterable
 from pathlib import Path
 import logging
 from ssl import create_default_context
 from email_validator import validate_email, EmailNotValidError
 
-# Set up logging
+# Set up logging without configuring the root logger
 logger = logging.getLogger(__name__)
-logging.basicConfig(level=logging.INFO)
+logger.addHandler(logging.NullHandler())
 
 
 class EmailSender:
@@ -25,7 +27,7 @@ class EmailSender:
             user_email_password: str,
             port: int = 587,
             timeout: int = 10,
-            validate_emails: bool = True
+            validate_emails: bool = True,
     ) -> None:
         self.user_email = self._validate_email(user_email) if validate_emails else user_email
         self.user_email_password = user_email_password
@@ -33,11 +35,31 @@ class EmailSender:
         self.port = port
         self.timeout = timeout
         self.validate_emails = validate_emails
+        template_dir = Path(__file__).resolve().parent / "templates"
         self.template_env = Environment(
-            loader=FileSystemLoader('templates'),
+            loader=FileSystemLoader(str(template_dir)),
             autoescape=select_autoescape(['html', 'xml'])
         )
         self.ssl_context = create_default_context()
+        logger.info("EmailSender initialised for %s", self.user_email)
+
+    @classmethod
+    def from_env(cls) -> "EmailSender":
+        """Create :class:`EmailSender` from environment variables.
+
+        Required variables are ``EMAIL``, ``SMTP_SERVER`` and ``EMAIL_PASSWORD``.
+        ``SMTP_PORT`` is optional and defaults to ``587``.
+        """
+        user_email = os.environ["EMAIL"]
+        server = os.environ["SMTP_SERVER"]
+        password = os.environ["EMAIL_PASSWORD"]
+        port = int(os.getenv("SMTP_PORT", 587))
+        return cls(
+            user_email=user_email,
+            server_smtp_address=server,
+            user_email_password=password,
+            port=port,
+        )
 
     def _validate_email(self, email_address: str) -> str:
         """Validate and normalize email address using email-validator."""
@@ -52,8 +74,7 @@ class EmailSender:
             self,
             subject: str,
             recipients: Iterable[str],
-            cc: Optional[Iterable[str]] = None,
-            bcc: Optional[Iterable[str]] = None
+            cc: Optional[Iterable[str]] = None
     ) -> MIMEMultipart:
         """Create MIME message with proper headers."""
         msg = MIMEMultipart()
@@ -70,10 +91,6 @@ class EmailSender:
             validated_cc = [self._validate_email(c) for c in cc] if self.validate_emails else cc
             msg['Cc'] = COMMASPACE.join(validated_cc)
 
-        if bcc:
-            validated_bcc = [self._validate_email(b) for b in bcc] if self.validate_emails else bcc
-            msg['Bcc'] = COMMASPACE.join(validated_bcc)
-
         return msg
 
     def _add_attachments(self, msg: MIMEMultipart, attachments: Iterable[str]) -> None:
@@ -105,7 +122,12 @@ class EmailSender:
             html: bool = False
     ) -> None:
         """Synchronous email sending with improved error handling."""
-        msg = self._create_base_message(subject, recipients, cc, bcc)
+        logger.info("Sending email to %s", ", ".join(recipients))
+        # Build the MIME message without exposing BCC recipients
+        msg = self._create_base_message(subject, recipients, cc)
+        validated_bcc = None
+        if bcc:
+            validated_bcc = [self._validate_email(b) for b in bcc] if self.validate_emails else list(bcc)
         msg.attach(MIMEText(message_body, 'html' if html else 'plain'))
 
         if attachments:
@@ -116,7 +138,12 @@ class EmailSender:
                 if use_tls:
                     server.starttls(context=self.ssl_context)
                 server.login(self.user_email, self.user_email_password)
-                server.send_message(msg)
+                all_recipients = list(recipients)
+                if cc:
+                    all_recipients.extend(cc)
+                if validated_bcc:
+                    all_recipients.extend(validated_bcc)
+                server.send_message(msg, to_addrs=all_recipients)
         except smtplib.SMTPException as e:
             logger.error(f"SMTP error occurred: {str(e)}")
             raise
@@ -124,6 +151,57 @@ class EmailSender:
             logger.error(f"Unexpected error: {str(e)}")
             raise
 
+    def send_bulk(
+            self,
+            recipients: Iterable[str],
+            subject: str,
+            message_body: str,
+            **kwargs,
+    ) -> None:
+        """Send the same message to many recipients individually."""
+        for recipient in recipients:
+            logger.info("Sending bulk email to %s", recipient)
+            self.send([recipient], subject, message_body, **kwargs)
+
+    async def send_async(
+            self,
+            recipients: Iterable[str],
+            subject: str,
+            message_body: str,
+            cc: Optional[Iterable[str]] = None,
+            bcc: Optional[Iterable[str]] = None,
+            attachments: Optional[Iterable[str]] = None,
+            use_tls: bool = True,
+            html: bool = False
+    ) -> None:
+        """Asynchronous email sending using aiosmtplib."""
+        msg = self._create_base_message(subject, recipients, cc)
+        validated_bcc = None
+        if bcc:
+            validated_bcc = [self._validate_email(b) for b in bcc] if self.validate_emails else list(bcc)
+        msg.attach(MIMEText(message_body, 'html' if html else 'plain'))
+
+        if attachments:
+            self._add_attachments(msg, attachments)
+
+        try:
+            async with aiosmtplib.SMTP(hostname=self.server_smtp_address, port=self.port, timeout=self.timeout) as server:
+                if use_tls:
+                    await server.starttls(context=self.ssl_context)
+                await server.login(self.user_email, self.user_email_password)
+                all_recipients = list(recipients)
+                if cc:
+                    all_recipients.extend(cc)
+                if validated_bcc:
+                    all_recipients.extend(validated_bcc)
+                await server.send_message(msg, to_addrs=all_recipients)
+        except aiosmtplib.errors.SMTPException as e:
+            logger.error(f"SMTP error occurred: {str(e)}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error: {str(e)}")
+            raise
+
     def send_template(
             self,
             recipient: str,
@@ -135,6 +213,7 @@ class EmailSender:
             use_tls: bool = True
     ) -> None:
         """Send email using Jinja2 template with autoescaping."""
+        logger.info("Sending templated email to %s using %s", recipient, template_name)
         template = self.template_env.get_template(template_name)
         html_content = template.render(**context)
         self.send([recipient], subject, html_content, cc=cc, attachments=attachments, use_tls=use_tls, html=True)
@@ -153,8 +232,7 @@ class SendAgent(EmailSender):
             cc: Optional[List[str]] = None,
             bcc: Optional[List[str]] = None,
             attachments: Optional[List[str]] = None,
-            tls: bool = True,
-            server_quit: bool = False
+            tls: bool = True
     ) -> None:
         logger.warning("SendAgent is deprecated, use EmailSender instead")
 
@@ -169,8 +247,6 @@ class SendAgent(EmailSender):
             use_tls=tls
         )
 
-        if server_quit:
-            self.server.quit()
 
     def send_mail_with_template(
             self,
@@ -180,8 +256,7 @@ class SendAgent(EmailSender):
             template_vars: dict,
             cc: Optional[List[str]] = None,
             attachments: Optional[List[str]] = None,
-            tls: bool = True,
-            server_quit: bool = False
+            tls: bool = True
     ) -> None:
         logger.warning("send_mail_with_template is deprecated, use send_template instead")
 
@@ -195,24 +270,3 @@ class SendAgent(EmailSender):
             use_tls=tls
         )
 
-        if server_quit:
-            self.server.quit()
-
-
-# Example usage
-if __name__ == "__main__":
-    sender = EmailSender(
-        user_email="your@email.com",
-        server_smtp_address="smtp.example.com",
-        user_email_password="password",
-        port=587
-    )
-
-    # Sync send
-    sender.send(
-        recipients=["gh.rambod@gmail.com"],
-        subject="Modern Email",
-        message_body="<h1>HTML Content</h1>",
-        html=True,
-        attachments=["important.pdf"]
-    )

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: MailToolsBox
-Version: 1.0.0
+Version: 1.0.1
 Summary: A modern and efficient Python library for sending emails with SMTP, Jinja2 templates, and attachments.
 Home-page: https://github.com/rambod/MailToolsBox
 Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.0.0.tar.gz
@@ -24,6 +24,7 @@ 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
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -33,6 +34,7 @@ Dynamic: download-url
 Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -49,8 +51,11 @@ MailToolsBox is a modern, feature-rich Python package designed for sending and m
 - **Attachment handling**
 - **Template-based email rendering using Jinja2**
 - **Secure email transactions with TLS/SSL**
+- **Asynchronous email sending via `send_async`**
 - **Email address validation**
 - **Logging for debugging and monitoring**
+- **Bulk email sending with `send_bulk`**
+- **Convenient configuration via environment variables using `from_env`**
 - **Backward compatibility with `SendAgent`**
 
 ---
@@ -157,7 +162,40 @@ sender.send(
 
 ---
 
-### 5. **Backward Compatibility with `SendAgent`**
+### 5. **Asynchronous Email Sending**
+
+Send emails without blocking using `send_async` and `asyncio`:
+
+```python
+import asyncio
+
+async def main():
+    await sender.send_async(
+        recipients=["recipient@example.com"],
+        subject="Async Example",
+        message_body="This email was sent asynchronously!"
+    )
+
+asyncio.run(main())
+```
+
+---
+
+### 6. **Bulk Email Sending**
+
+Send the same message to many recipients individually, ensuring privacy:
+
+```python
+sender.send_bulk(
+    recipients=["user1@example.com", "user2@example.com"],
+    subject="Announcement",
+    message_body="This email is sent separately to each recipient!",
+)
+```
+
+---
+
+### 7. **Backward Compatibility with `SendAgent`**
 
 For those migrating from earlier versions, `SendAgent` ensures seamless compatibility:
 
@@ -174,10 +212,29 @@ legacy_sender = SendAgent(
 legacy_sender.send_mail(
     recipient_email=["recipient@example.com"],
     subject="Legacy Compatibility Test",
-    message_body="Testing backward compatibility."
+        message_body="Testing backward compatibility."
 )
 ```
 
+---
+
+### 8. **Retrieving Emails via IMAP**
+
+`ImapAgent` can be used to fetch messages from an IMAP mailbox. It supports
+loading configuration from environment variables with `from_env` and can be
+used as a context manager to ensure connections are closed properly.
+
+```python
+from MailToolsBox import ImapAgent
+
+# Using environment variables IMAP_EMAIL, IMAP_PASSWORD and IMAP_SERVER
+agent = ImapAgent.from_env()
+
+with agent as imap:
+    imap.download_mail_text(path="/tmp/")
+```
+
+
 ---
 
 ## Configuration & Security Best Practices
@@ -189,14 +246,7 @@ legacy_sender.send_mail(
 Example using environment variables:
 
 ```python
-import os
-
-sender = EmailSender(
-    user_email=os.getenv("EMAIL"),
-    server_smtp_address=os.getenv("SMTP_SERVER"),
-    user_email_password=os.getenv("EMAIL_PASSWORD"),
-    port=int(os.getenv("SMTP_PORT", 587))
-)
+sender = EmailSender.from_env()
 ```
 
 ---
@@ -234,7 +284,7 @@ MailToolsBox is an open-source project. Contributions are welcome! To contribute
 3. Implement changes and write tests.
 4. Submit a pull request for review.
 
-For discussions, visit **[rambod.net](https://www.rambod.net)**.
+For discussions, visit **[rambod.net](https://www.rambod.net)**. **[mailtoolsbox](https://rambod.net/portfolio/mailtoolsbox/)**
 
 ---
 

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox.egg-info/SOURCES.txt

@@ -8,4 +8,7 @@ MailToolsBox.egg-info/PKG-INFO
 MailToolsBox.egg-info/SOURCES.txt
 MailToolsBox.egg-info/dependency_links.txt
 MailToolsBox.egg-info/requires.txt
-MailToolsBox.egg-info/top_level.txt
+MailToolsBox.egg-info/top_level.txt
+tests/__init__.py
+tests/test_imap_agent.py
+tests/test_mail_sender.py

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox.egg-info/requires.txt

@@ -1,2 +1,3 @@
 Jinja2>=3.0.2
 email-validator>=2.0.0
+aiosmtplib>=2.0.0

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/MailToolsBox.egg-info/top_level.txt

@@ -1 +1,2 @@
 MailToolsBox
+tests

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: MailToolsBox
-Version: 1.0.0
+Version: 1.0.1
 Summary: A modern and efficient Python library for sending emails with SMTP, Jinja2 templates, and attachments.
 Home-page: https://github.com/rambod/MailToolsBox
 Download-URL: https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.0.0.tar.gz
@@ -24,6 +24,7 @@ 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
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -33,6 +34,7 @@ Dynamic: download-url
 Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -49,8 +51,11 @@ MailToolsBox is a modern, feature-rich Python package designed for sending and m
 - **Attachment handling**
 - **Template-based email rendering using Jinja2**
 - **Secure email transactions with TLS/SSL**
+- **Asynchronous email sending via `send_async`**
 - **Email address validation**
 - **Logging for debugging and monitoring**
+- **Bulk email sending with `send_bulk`**
+- **Convenient configuration via environment variables using `from_env`**
 - **Backward compatibility with `SendAgent`**
 
 ---
@@ -157,7 +162,40 @@ sender.send(
 
 ---
 
-### 5. **Backward Compatibility with `SendAgent`**
+### 5. **Asynchronous Email Sending**
+
+Send emails without blocking using `send_async` and `asyncio`:
+
+```python
+import asyncio
+
+async def main():
+    await sender.send_async(
+        recipients=["recipient@example.com"],
+        subject="Async Example",
+        message_body="This email was sent asynchronously!"
+    )
+
+asyncio.run(main())
+```
+
+---
+
+### 6. **Bulk Email Sending**
+
+Send the same message to many recipients individually, ensuring privacy:
+
+```python
+sender.send_bulk(
+    recipients=["user1@example.com", "user2@example.com"],
+    subject="Announcement",
+    message_body="This email is sent separately to each recipient!",
+)
+```
+
+---
+
+### 7. **Backward Compatibility with `SendAgent`**
 
 For those migrating from earlier versions, `SendAgent` ensures seamless compatibility:
 
@@ -174,10 +212,29 @@ legacy_sender = SendAgent(
 legacy_sender.send_mail(
     recipient_email=["recipient@example.com"],
     subject="Legacy Compatibility Test",
-    message_body="Testing backward compatibility."
+        message_body="Testing backward compatibility."
 )
 ```
 
+---
+
+### 8. **Retrieving Emails via IMAP**
+
+`ImapAgent` can be used to fetch messages from an IMAP mailbox. It supports
+loading configuration from environment variables with `from_env` and can be
+used as a context manager to ensure connections are closed properly.
+
+```python
+from MailToolsBox import ImapAgent
+
+# Using environment variables IMAP_EMAIL, IMAP_PASSWORD and IMAP_SERVER
+agent = ImapAgent.from_env()
+
+with agent as imap:
+    imap.download_mail_text(path="/tmp/")
+```
+
+
 ---
 
 ## Configuration & Security Best Practices
@@ -189,14 +246,7 @@ legacy_sender.send_mail(
 Example using environment variables:
 
 ```python
-import os
-
-sender = EmailSender(
-    user_email=os.getenv("EMAIL"),
-    server_smtp_address=os.getenv("SMTP_SERVER"),
-    user_email_password=os.getenv("EMAIL_PASSWORD"),
-    port=int(os.getenv("SMTP_PORT", 587))
-)
+sender = EmailSender.from_env()
 ```
 
 ---
@@ -234,7 +284,7 @@ MailToolsBox is an open-source project. Contributions are welcome! To contribute
 3. Implement changes and write tests.
 4. Submit a pull request for review.
 
-For discussions, visit **[rambod.net](https://www.rambod.net)**.
+For discussions, visit **[rambod.net](https://www.rambod.net)**. **[mailtoolsbox](https://rambod.net/portfolio/mailtoolsbox/)**
 
 ---
 

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/README.md

@@ -10,8 +10,11 @@ MailToolsBox is a modern, feature-rich Python package designed for sending and m
 - **Attachment handling**
 - **Template-based email rendering using Jinja2**
 - **Secure email transactions with TLS/SSL**
+- **Asynchronous email sending via `send_async`**
 - **Email address validation**
 - **Logging for debugging and monitoring**
+- **Bulk email sending with `send_bulk`**
+- **Convenient configuration via environment variables using `from_env`**
 - **Backward compatibility with `SendAgent`**
 
 ---
@@ -118,7 +121,40 @@ sender.send(
 
 ---
 
-### 5. **Backward Compatibility with `SendAgent`**
+### 5. **Asynchronous Email Sending**
+
+Send emails without blocking using `send_async` and `asyncio`:
+
+```python
+import asyncio
+
+async def main():
+    await sender.send_async(
+        recipients=["recipient@example.com"],
+        subject="Async Example",
+        message_body="This email was sent asynchronously!"
+    )
+
+asyncio.run(main())
+```
+
+---
+
+### 6. **Bulk Email Sending**
+
+Send the same message to many recipients individually, ensuring privacy:
+
+```python
+sender.send_bulk(
+    recipients=["user1@example.com", "user2@example.com"],
+    subject="Announcement",
+    message_body="This email is sent separately to each recipient!",
+)
+```
+
+---
+
+### 7. **Backward Compatibility with `SendAgent`**
 
 For those migrating from earlier versions, `SendAgent` ensures seamless compatibility:
 
@@ -135,10 +171,29 @@ legacy_sender = SendAgent(
 legacy_sender.send_mail(
     recipient_email=["recipient@example.com"],
     subject="Legacy Compatibility Test",
-    message_body="Testing backward compatibility."
+        message_body="Testing backward compatibility."
 )
 ```
 
+---
+
+### 8. **Retrieving Emails via IMAP**
+
+`ImapAgent` can be used to fetch messages from an IMAP mailbox. It supports
+loading configuration from environment variables with `from_env` and can be
+used as a context manager to ensure connections are closed properly.
+
+```python
+from MailToolsBox import ImapAgent
+
+# Using environment variables IMAP_EMAIL, IMAP_PASSWORD and IMAP_SERVER
+agent = ImapAgent.from_env()
+
+with agent as imap:
+    imap.download_mail_text(path="/tmp/")
+```
+
+
 ---
 
 ## Configuration & Security Best Practices
@@ -150,14 +205,7 @@ legacy_sender.send_mail(
 Example using environment variables:
 
 ```python
-import os
-
-sender = EmailSender(
-    user_email=os.getenv("EMAIL"),
-    server_smtp_address=os.getenv("SMTP_SERVER"),
-    user_email_password=os.getenv("EMAIL_PASSWORD"),
-    port=int(os.getenv("SMTP_PORT", 587))
-)
+sender = EmailSender.from_env()
 ```
 
 ---
@@ -195,7 +243,7 @@ MailToolsBox is an open-source project. Contributions are welcome! To contribute
 3. Implement changes and write tests.
 4. Submit a pull request for review.
 
-For discussions, visit **[rambod.net](https://www.rambod.net)**.
+For discussions, visit **[rambod.net](https://www.rambod.net)**. **[mailtoolsbox](https://rambod.net/portfolio/mailtoolsbox/)**
 
 ---
 

{mailtoolsbox-1.0.0 → mailtoolsbox-1.0.1}/setup.py

@@ -3,7 +3,7 @@ from setuptools import setup, find_packages
 setup(
     name='MailToolsBox',
     packages=find_packages(),
-    version='1.0.0',  # Increased version for major revamp
+    version='1.0.1',  # Increased version for major revamp
     license='MIT',
     description='A modern and efficient Python library for sending emails with SMTP, Jinja2 templates, and attachments.',
     long_description=open('README.md', encoding='utf-8').read(),
@@ -15,7 +15,8 @@ setup(
     keywords=['Mail', 'SMTP', 'email', 'tools', 'attachments', 'Jinja2', 'Python', 'email-validation'],
     install_requires=[
         "Jinja2>=3.0.2",
-        "email-validator>=2.0.0"
+        "email-validator>=2.0.0",
+        "aiosmtplib>=2.0.0"
     ],
     classifiers=[
         'Development Status :: 5 - Production/Stable',

mailtoolsbox-1.0.1/tests/test_imap_agent.py

@@ -0,0 +1,146 @@
+import json
+import email
+from email.mime.text import MIMEText
+from unittest import mock
+import os
+import types
+import sys
+
+import pytest
+
+# Provide dummy aiosmtplib for indirect imports via mailSender
+sys.modules.setdefault(
+    "aiosmtplib",
+    types.SimpleNamespace(SMTP=None, errors=types.SimpleNamespace(SMTPException=Exception)),
+)
+# Minimal stub for jinja2 used by EmailSender imports
+sys.modules.setdefault(
+    "jinja2",
+    types.SimpleNamespace(
+        Environment=lambda **kwargs: types.SimpleNamespace(get_template=lambda name: types.SimpleNamespace(render=lambda **kw: "")),
+        FileSystemLoader=lambda *args, **kwargs: None,
+        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
+
+
+class DummyMail:
+    def __init__(self, message_bytes):
+        self.message_bytes = message_bytes
+        self.closed = False
+        self.logged_in = False
+        self.selected = None
+    def login(self, user, password):
+        self.logged_in = True
+    def select(self, mailbox):
+        self.selected = mailbox
+        return ('OK', [b''])
+    def uid(self, command, *args):
+        if command == 'search':
+            return ('OK', [b'1'])
+        elif command == 'fetch':
+            return ('OK', [(None, self.message_bytes)])
+    def close(self):
+        self.closed = True
+    def logout(self):
+        self.closed = True
+    def __enter__(self):
+        return self
+    def __exit__(self, exc_type, exc, tb):
+        pass
+
+
+def sample_message_bytes():
+    msg = MIMEText('body text')
+    msg['From'] = 'from@example.com'
+    msg['To'] = 'to@example.com'
+    msg['Subject'] = 'Test'
+    msg['Date'] = 'Wed, 20 Sep 2023 12:00:00 -0000'
+    return msg.as_bytes()
+
+
+def test_login_account(monkeypatch):
+    dummy = DummyMail(sample_message_bytes())
+    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda addr: dummy)
+    agent = ImapAgent('user', 'pass', 'imap.example.com')
+    agent.login_account()
+    assert agent.mail is dummy
+    assert dummy.logged_in
+
+
+def test_download_mail_text(tmp_path, monkeypatch):
+    message_bytes = sample_message_bytes()
+    dummy = DummyMail(message_bytes)
+    agent = ImapAgent('user', 'pass', 'imap.example.com')
+    agent.mail = dummy
+
+    agent.download_mail_text(path=str(tmp_path) + os.sep)
+
+    file_path = tmp_path / 'email.txt'
+    assert file_path.exists()
+    content = file_path.read_text()
+    assert 'body text' in content
+    assert dummy.closed
+
+
+def test_download_mail_json(tmp_path, monkeypatch):
+    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)
+
+    agent = ImapAgent('user', 'pass', 'imap.example.com')
+    result = agent.download_mail_json(save=True, path=str(tmp_path) + os.sep)
+
+    data = json.loads(result)
+    assert isinstance(data, list)
+    assert data[0]['subject'] == 'Test'
+    file_path = tmp_path / 'mail.json'
+    assert file_path.exists()
+    assert dummy.closed
+
+
+def test_download_mail_msg(tmp_path):
+    message_bytes = sample_message_bytes()
+    dummy = DummyMail(message_bytes)
+    agent = ImapAgent('user', 'pass', 'imap.example.com')
+    agent.login_account = lambda: setattr(agent, 'mail', dummy)
+
+    agent.download_mail_msg(path=str(tmp_path) + os.sep)
+
+    file_path = tmp_path / 'email_0.msg'
+    assert file_path.exists()
+
+
+def test_from_env(monkeypatch):
+    monkeypatch.setenv("IMAP_EMAIL", "env@example.com")
+    monkeypatch.setenv("IMAP_PASSWORD", "secret")
+    monkeypatch.setenv("IMAP_SERVER", "imap.env.com")
+
+    agent = ImapAgent.from_env()
+
+    assert agent.email_account == "env@example.com"
+    assert agent.password == "secret"
+    assert agent.server_address == "imap.env.com"
+
+
+def test_context_manager(monkeypatch):
+    dummy = DummyMail(sample_message_bytes())
+    monkeypatch.setattr('imaplib.IMAP4_SSL', lambda addr: dummy)
+
+    with ImapAgent('user', 'pass', 'imap.example.com') as agent:
+        assert agent.mail is dummy
+        assert dummy.logged_in
+    assert dummy.closed
+    assert agent.mail is None
+
+

mailtoolsbox-1.0.1/tests/test_mail_sender.py

@@ -0,0 +1,100 @@
+import builtins
+import smtplib
+from unittest import mock
+import types
+import sys
+import pytest
+
+# Provide dummy aiosmtplib to satisfy imports
+sys.modules.setdefault(
+    "aiosmtplib",
+    types.SimpleNamespace(SMTP=None, errors=types.SimpleNamespace(SMTPException=Exception)),
+)
+# Minimal stub for jinja2
+sys.modules.setdefault(
+    "jinja2",
+    types.SimpleNamespace(
+        Environment=lambda **kwargs: types.SimpleNamespace(get_template=lambda name: types.SimpleNamespace(render=lambda **kw: "")),
+        FileSystemLoader=lambda *args, **kwargs: None,
+        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
+
+
+def test_email_sender_send(monkeypatch):
+    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",
+        port=25,
+    )
+
+    sender.send(
+        recipients=["to@example.com"],
+        subject="Subj",
+        message_body="Body",
+        cc=["cc@example.com"],
+        bcc=["bcc@example.com"],
+        use_tls=True,
+    )
+
+    smtp_class.assert_called_with("smtp.example.com", 25, timeout=10)
+    smtp_instance.starttls.assert_called()
+    smtp_instance.login.assert_called_with("user@example.com", "pass")
+    smtp_instance.send_message.assert_called()
+
+    args, kwargs = smtp_instance.send_message.call_args
+    msg = args[0]
+    to_addrs = kwargs["to_addrs"]
+    assert set(to_addrs) == {"to@example.com", "cc@example.com", "bcc@example.com"}
+    assert msg["To"] == "to@example.com"
+    assert msg["Cc"] == "cc@example.com"
+
+
+def test_email_sender_from_env(monkeypatch):
+    monkeypatch.setenv("EMAIL", "env@example.com")
+    monkeypatch.setenv("SMTP_SERVER", "smtp.env.com")
+    monkeypatch.setenv("EMAIL_PASSWORD", "secret")
+    monkeypatch.setenv("SMTP_PORT", "2525")
+
+    sender = EmailSender.from_env()
+
+    assert sender.user_email == "env@example.com"
+    assert sender.server_smtp_address == "smtp.env.com"
+    assert sender.user_email_password == "secret"
+    assert sender.port == 2525
+
+
+def test_send_bulk(monkeypatch):
+    sent = []
+
+    class DummySender(EmailSender):
+        def __init__(self):
+            pass
+
+        def send(self, recipients, subject, message_body, **kwargs):
+            sent.append(recipients[0])
+
+    sender = DummySender()
+
+    sender.send_bulk(["a@example.com", "b@example.com"], "subj", "body")
+
+    assert sent == ["a@example.com", "b@example.com"]
+
+

mailtoolsbox-1.0.0/MailToolsBox/__init__.py

@@ -1,2 +0,0 @@
-from MailToolsBox.mailSender import SendAgent
-from MailToolsBox.imapClient import ImapAgent