MailToolsBox 0.1.0.4__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-0.1.0.4 → 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.1/MailToolsBox/mailSender.py

@@ -0,0 +1,272 @@
+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 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 without configuring the root logger
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class EmailSender:
+    """Modern email sender with sync/async support and enhanced features."""
+
+    def __init__(
+            self,
+            user_email: str,
+            server_smtp_address: str,
+            user_email_password: str,
+            port: int = 587,
+            timeout: int = 10,
+            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
+        self.server_smtp_address = server_smtp_address
+        self.port = port
+        self.timeout = timeout
+        self.validate_emails = validate_emails
+        template_dir = Path(__file__).resolve().parent / "templates"
+        self.template_env = Environment(
+            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."""
+        try:
+            result = validate_email(email_address, check_deliverability=False)
+            return result.normalized
+        except EmailNotValidError as e:
+            logger.error(f"Invalid email address: {email_address}")
+            raise ValueError(f"Invalid email address: {email_address}") from e
+
+    def _create_base_message(
+            self,
+            subject: str,
+            recipients: Iterable[str],
+            cc: Optional[Iterable[str]] = None
+    ) -> MIMEMultipart:
+        """Create MIME message with proper headers."""
+        msg = MIMEMultipart()
+        msg['From'] = self.user_email
+        msg['Subject'] = subject
+        msg['Date'] = formatdate(localtime=True)
+
+        if self.validate_emails:
+            recipients = [self._validate_email(r) for r in recipients]
+
+        msg['To'] = COMMASPACE.join(recipients)
+
+        if cc:
+            validated_cc = [self._validate_email(c) for c in cc] if self.validate_emails else cc
+            msg['Cc'] = COMMASPACE.join(validated_cc)
+
+        return msg
+
+    def _add_attachments(self, msg: MIMEMultipart, attachments: Iterable[str]) -> None:
+        """Add multiple attachments to the message."""
+        for file_path in attachments:
+            path = Path(file_path)
+            if not path.exists():
+                logger.warning(f"Attachment not found: {file_path}")
+                continue
+
+            with open(path, 'rb') as f:
+                part = MIMEApplication(
+                    f.read(),
+                    Name=path.name
+                )
+            part['Content-Disposition'] = f'attachment; filename="{path.name}"'
+            msg.attach(part)
+
+
+    def send(
+            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:
+        """Synchronous email sending with improved error handling."""
+        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:
+            self._add_attachments(msg, attachments)
+
+        try:
+            with smtplib.SMTP(self.server_smtp_address, self.port, timeout=self.timeout) as server:
+                if use_tls:
+                    server.starttls(context=self.ssl_context)
+                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)
+                server.send_message(msg, to_addrs=all_recipients)
+        except smtplib.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_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,
+            subject: str,
+            template_name: str,
+            context: dict,
+            cc: Optional[Iterable[str]] = None,
+            attachments: Optional[Iterable[str]] = None,
+            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)
+
+
+
+# Backward compatibility layer
+class SendAgent(EmailSender):
+    """Legacy compatibility layer maintaining original interface."""
+
+    def send_mail(
+            self,
+            recipient_email: Optional[List[str]],
+            subject: str,
+            message_body: str,
+            cc: Optional[List[str]] = None,
+            bcc: Optional[List[str]] = None,
+            attachments: Optional[List[str]] = None,
+            tls: bool = True
+    ) -> None:
+        logger.warning("SendAgent is deprecated, use EmailSender instead")
+
+        # Convert parameters to new format
+        self.send(
+            recipients=recipient_email,
+            subject=subject,
+            message_body=message_body,
+            cc=cc,
+            bcc=bcc,
+            attachments=attachments,
+            use_tls=tls
+        )
+
+
+    def send_mail_with_template(
+            self,
+            recipient_email: str,
+            subject: str,
+            template_path: str,
+            template_vars: dict,
+            cc: Optional[List[str]] = None,
+            attachments: Optional[List[str]] = None,
+            tls: bool = True
+    ) -> None:
+        logger.warning("send_mail_with_template is deprecated, use send_template instead")
+
+        self.send_template(
+            recipient=recipient_email,
+            subject=subject,
+            template_name=template_path,
+            context=template_vars,
+            cc=cc,
+            attachments=attachments,
+            use_tls=tls
+        )
+

mailtoolsbox-1.0.1/MailToolsBox.egg-info/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: MailToolsBox
+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
+Author: Rambod Ghashghai
+Author-email: gh.rambod@gmail.com
+License: MIT
+Keywords: Mail,SMTP,email,tools,attachments,Jinja2,Python,email-validation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Communications :: Email
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.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
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# MailToolsBox
+
+MailToolsBox is a modern, feature-rich Python package designed for sending and managing emails with ease. It provides robust functionality for handling SMTP email sending, template-based emails using Jinja2, attachments, CC/BCC support, and email validation. Additionally, MailToolsBox ensures backward compatibility with legacy implementations.
+
+## Features
+
+- **Send emails via SMTP with ease**
+- **Support for multiple recipients (To, CC, BCC)**
+- **HTML and plain text email support**
+- **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`**
+
+---
+
+## Installation
+
+Install MailToolsBox from PyPI using pip:
+
+```bash
+pip install MailToolsBox
+```
+
+---
+
+## Getting Started
+
+### 1. **Sending a Basic Email**
+
+The `EmailSender` class is the primary interface for sending emails. Below is an example of sending a simple plain text email:
+
+```python
+from MailToolsBox import EmailSender
+
+# Email configuration
+sender = EmailSender(
+    user_email="your@email.com",
+    server_smtp_address="smtp.example.com",
+    user_email_password="yourpassword",
+    port=587
+)
+
+# Sending email
+sender.send(
+    recipients=["recipient@example.com"],
+    subject="Test Email",
+    message_body="Hello, this is a test email!"
+)
+```
+
+---
+
+### 2. **Sending an HTML Email with Attachments**
+
+```python
+sender.send(
+    recipients=["recipient@example.com"],
+    subject="HTML Email Example",
+    message_body="""<h1>Welcome!</h1><p>This is an <strong>HTML email</strong>.</p>""",
+
+    html=True,
+    attachments=["/path/to/document.pdf"]
+)
+```
+
+---
+
+### 3. **Using Email Templates (Jinja2)**
+
+MailToolsBox allows sending emails using Jinja2 templates stored in the `templates/` directory.
+
+#### **Example Template (`templates/welcome.html`)**:
+
+```html
+<html>
+<head>
+    <title>Welcome</title>
+</head>
+<body>
+    <h1>Welcome, {{ username }}!</h1>
+    <p>Click <a href="{{ activation_link }}">here</a> to activate your account.</p>
+</body>
+</html>
+```
+
+#### **Sending an Email with a Template**:
+
+```python
+context = {
+    "username": "John Doe",
+    "activation_link": "https://example.com/activate"
+}
+
+sender.send_template(
+    recipient="recipient@example.com",
+    subject="Welcome to Our Service",
+    template_name="welcome.html",
+    context=context
+)
+```
+
+---
+
+### 4. **CC, BCC, and Multiple Recipients**
+
+```python
+sender.send(
+    recipients=["recipient@example.com"],
+    subject="CC & BCC Example",
+    message_body="This email has CC and BCC recipients!",
+    cc=["cc@example.com"],
+    bcc=["bcc@example.com"]
+)
+```
+
+---
+
+### 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:
+
+```python
+from MailToolsBox import SendAgent
+
+legacy_sender = SendAgent(
+    user_email="your@email.com",
+    server_smtp_address="smtp.example.com",
+    user_email_password="yourpassword",
+    port=587
+)
+
+legacy_sender.send_mail(
+    recipient_email=["recipient@example.com"],
+    subject="Legacy Compatibility Test",
+        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
+
+- **Use environment variables** instead of hardcoding credentials.
+- **Enable 2FA** on your email provider and use app passwords if required.
+- **Use TLS/SSL** to ensure secure email delivery.
+
+Example using environment variables:
+
+```python
+sender = EmailSender.from_env()
+```
+
+---
+
+## Error Handling & Logging
+
+MailToolsBox provides built-in logging to help debug issues:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+Example of handling exceptions:
+
+```python
+try:
+    sender.send(
+        recipients=["recipient@example.com"],
+        subject="Error Handling Test",
+        message_body="This is a test email."
+    )
+except Exception as e:
+    print(f"Failed to send email: {e}")
+```
+
+---
+
+## Contributing
+
+MailToolsBox is an open-source project. Contributions are welcome! To contribute:
+
+1. Fork the repository on GitHub.
+2. Create a new feature branch.
+3. Implement changes and write tests.
+4. Submit a pull request for review.
+
+For discussions, visit **[rambod.net](https://www.rambod.net)**. **[mailtoolsbox](https://rambod.net/portfolio/mailtoolsbox/)**
+
+---
+
+## License
+
+MailToolsBox is licensed under the MIT License. See the [LICENSE](https://choosealicense.com/licenses/mit/) for details.

{MailToolsBox-0.1.0.4 → 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.1/MailToolsBox.egg-info/requires.txt

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

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

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