# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/rambod/MailToolsBox",
"name": "MailToolsBox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Mail, SMTP, email, tools, attachments, Jinja2, Python, email-validation",
"author": "Rambod Ghashghai",
"author_email": "gh.rambod@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/06/c76f6f68591d02d92b380addcb7d7fd599ee5190e267231b318d32584a06/mailtoolsbox-1.0.0.tar.gz",
"platform": null,
"description": "# MailToolsBox\r\n\r\nMailToolsBox 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.\r\n\r\n## Features\r\n\r\n- **Send emails via SMTP with ease**\r\n- **Support for multiple recipients (To, CC, BCC)**\r\n- **HTML and plain text email support**\r\n- **Attachment handling**\r\n- **Template-based email rendering using Jinja2**\r\n- **Secure email transactions with TLS/SSL**\r\n- **Email address validation**\r\n- **Logging for debugging and monitoring**\r\n- **Backward compatibility with `SendAgent`**\r\n\r\n---\r\n\r\n## Installation\r\n\r\nInstall MailToolsBox from PyPI using pip:\r\n\r\n```bash\r\npip install MailToolsBox\r\n```\r\n\r\n---\r\n\r\n## Getting Started\r\n\r\n### 1. **Sending a Basic Email**\r\n\r\nThe `EmailSender` class is the primary interface for sending emails. Below is an example of sending a simple plain text email:\r\n\r\n```python\r\nfrom MailToolsBox import EmailSender\r\n\r\n# Email configuration\r\nsender = EmailSender(\r\n user_email=\"your@email.com\",\r\n server_smtp_address=\"smtp.example.com\",\r\n user_email_password=\"yourpassword\",\r\n port=587\r\n)\r\n\r\n# Sending email\r\nsender.send(\r\n recipients=[\"recipient@example.com\"],\r\n subject=\"Test Email\",\r\n message_body=\"Hello, this is a test email!\"\r\n)\r\n```\r\n\r\n---\r\n\r\n### 2. **Sending an HTML Email with Attachments**\r\n\r\n```python\r\nsender.send(\r\n recipients=[\"recipient@example.com\"],\r\n subject=\"HTML Email Example\",\r\n message_body=\"\"\"<h1>Welcome!</h1><p>This is an <strong>HTML email</strong>.</p>\"\"\",\r\n\r\n html=True,\r\n attachments=[\"/path/to/document.pdf\"]\r\n)\r\n```\r\n\r\n---\r\n\r\n### 3. **Using Email Templates (Jinja2)**\r\n\r\nMailToolsBox allows sending emails using Jinja2 templates stored in the `templates/` directory.\r\n\r\n#### **Example Template (`templates/welcome.html`)**:\r\n\r\n```html\r\n<html>\r\n<head>\r\n <title>Welcome</title>\r\n</head>\r\n<body>\r\n <h1>Welcome, {{ username }}!</h1>\r\n <p>Click <a href=\"{{ activation_link }}\">here</a> to activate your account.</p>\r\n</body>\r\n</html>\r\n```\r\n\r\n#### **Sending an Email with a Template**:\r\n\r\n```python\r\ncontext = {\r\n \"username\": \"John Doe\",\r\n \"activation_link\": \"https://example.com/activate\"\r\n}\r\n\r\nsender.send_template(\r\n recipient=\"recipient@example.com\",\r\n subject=\"Welcome to Our Service\",\r\n template_name=\"welcome.html\",\r\n context=context\r\n)\r\n```\r\n\r\n---\r\n\r\n### 4. **CC, BCC, and Multiple Recipients**\r\n\r\n```python\r\nsender.send(\r\n recipients=[\"recipient@example.com\"],\r\n subject=\"CC & BCC Example\",\r\n message_body=\"This email has CC and BCC recipients!\",\r\n cc=[\"cc@example.com\"],\r\n bcc=[\"bcc@example.com\"]\r\n)\r\n```\r\n\r\n---\r\n\r\n### 5. **Backward Compatibility with `SendAgent`**\r\n\r\nFor those migrating from earlier versions, `SendAgent` ensures seamless compatibility:\r\n\r\n```python\r\nfrom MailToolsBox import SendAgent\r\n\r\nlegacy_sender = SendAgent(\r\n user_email=\"your@email.com\",\r\n server_smtp_address=\"smtp.example.com\",\r\n user_email_password=\"yourpassword\",\r\n port=587\r\n)\r\n\r\nlegacy_sender.send_mail(\r\n recipient_email=[\"recipient@example.com\"],\r\n subject=\"Legacy Compatibility Test\",\r\n message_body=\"Testing backward compatibility.\"\r\n)\r\n```\r\n\r\n---\r\n\r\n## Configuration & Security Best Practices\r\n\r\n- **Use environment variables** instead of hardcoding credentials.\r\n- **Enable 2FA** on your email provider and use app passwords if required.\r\n- **Use TLS/SSL** to ensure secure email delivery.\r\n\r\nExample using environment variables:\r\n\r\n```python\r\nimport os\r\n\r\nsender = EmailSender(\r\n user_email=os.getenv(\"EMAIL\"),\r\n server_smtp_address=os.getenv(\"SMTP_SERVER\"),\r\n user_email_password=os.getenv(\"EMAIL_PASSWORD\"),\r\n port=int(os.getenv(\"SMTP_PORT\", 587))\r\n)\r\n```\r\n\r\n---\r\n\r\n## Error Handling & Logging\r\n\r\nMailToolsBox provides built-in logging to help debug issues:\r\n\r\n```python\r\nimport logging\r\nlogging.basicConfig(level=logging.INFO)\r\n```\r\n\r\nExample of handling exceptions:\r\n\r\n```python\r\ntry:\r\n sender.send(\r\n recipients=[\"recipient@example.com\"],\r\n subject=\"Error Handling Test\",\r\n message_body=\"This is a test email.\"\r\n )\r\nexcept Exception as e:\r\n print(f\"Failed to send email: {e}\")\r\n```\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nMailToolsBox is an open-source project. Contributions are welcome! To contribute:\r\n\r\n1. Fork the repository on GitHub.\r\n2. Create a new feature branch.\r\n3. Implement changes and write tests.\r\n4. Submit a pull request for review.\r\n\r\nFor discussions, visit **[rambod.net](https://www.rambod.net)**.\r\n\r\n---\r\n\r\n## License\r\n\r\nMailToolsBox is licensed under the MIT License. See the [LICENSE](https://choosealicense.com/licenses/mit/) for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern and efficient Python library for sending emails with SMTP, Jinja2 templates, and attachments.",
"version": "1.0.0",
"project_urls": {
"Download": "https://github.com/rambod/MailToolsBox/archive/refs/tags/v1.0.0.tar.gz",
"Homepage": "https://github.com/rambod/MailToolsBox"
},
"split_keywords": [
"mail",
" smtp",
" email",
" tools",
" attachments",
" jinja2",
" python",
" email-validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "239855115bd2cea0833b618ffba70ea716263b231d9b4d24cc021e9281998ef3",
"md5": "c3ecf1f2fb86b7c5ccaaf9e3a230fc54",
"sha256": "8ac439aa12f652922acbb69da80f0da7edc43c0d3fef2ce601c1016e292ed908"
},
"downloads": -1,
"filename": "MailToolsBox-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3ecf1f2fb86b7c5ccaaf9e3a230fc54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7972,
"upload_time": "2025-02-03T09:40:39",
"upload_time_iso_8601": "2025-02-03T09:40:39.974250Z",
"url": "https://files.pythonhosted.org/packages/23/98/55115bd2cea0833b618ffba70ea716263b231d9b4d24cc021e9281998ef3/MailToolsBox-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e606c76f6f68591d02d92b380addcb7d7fd599ee5190e267231b318d32584a06",
"md5": "b97b4b6bce7b96ce90a4e4cb92b70546",
"sha256": "5ae96c62a0ab61f93fe430969e9d0fbdc613356103afd480970c38967402ed0c"
},
"downloads": -1,
"filename": "mailtoolsbox-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b97b4b6bce7b96ce90a4e4cb92b70546",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7336,
"upload_time": "2025-02-03T09:40:41",
"upload_time_iso_8601": "2025-02-03T09:40:41.861566Z",
"url": "https://files.pythonhosted.org/packages/e6/06/c76f6f68591d02d92b380addcb7d7fd599ee5190e267231b318d32584a06/mailtoolsbox-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 09:40:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rambod",
"github_project": "MailToolsBox",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mailtoolsbox"
}
JSON
