MailToolsBox 0.1.0.4__tar.gz → 1.0.0__tar.gz

mailtoolsbox-1.0.0/MailToolsBox/mailSender.py

@@ -0,0 +1,218 @@
+import smtplib
+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 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
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+
+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
+        self.template_env = Environment(
+            loader=FileSystemLoader('templates'),
+            autoescape=select_autoescape(['html', 'xml'])
+        )
+        self.ssl_context = create_default_context()
+
+    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,
+            bcc: 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)
+
+        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:
+        """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."""
+        msg = self._create_base_message(subject, recipients, cc, 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)
+                server.send_message(msg)
+        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_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."""
+        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,
+            server_quit: bool = False
+    ) -> 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
+        )
+
+        if server_quit:
+            self.server.quit()
+
+    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,
+            server_quit: bool = False
+    ) -> 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
+        )
+
+        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.egg-info/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.2
+Name: MailToolsBox
+Version: 1.0.0
+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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+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**
+- **Email address validation**
+- **Logging for debugging and monitoring**
+- **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. **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."
+)
+```
+
+---
+
+## 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
+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))
+)
+```
+
+---
+
+## 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)**.
+
+---
+
+## License
+
+MailToolsBox is licensed under the MIT License. See the [LICENSE](https://choosealicense.com/licenses/mit/) for details.

mailtoolsbox-1.0.0/MailToolsBox.egg-info/requires.txt

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

mailtoolsbox-1.0.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.2
+Name: MailToolsBox
+Version: 1.0.0
+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
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+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**
+- **Email address validation**
+- **Logging for debugging and monitoring**
+- **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. **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."
+)
+```
+
+---
+
+## 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
+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))
+)
+```
+
+---
+
+## 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)**.
+
+---
+
+## License
+
+MailToolsBox is licensed under the MIT License. See the [LICENSE](https://choosealicense.com/licenses/mit/) for details.